Deals

Replace the locations of a deal

PUT/deals/{deal_id}/locations
deals:writereplace_deal_locationsDestructiveIdempotent

Makes the deal's locations exactly the items you send. An item with an id updates that link and you send only what changes, one without creates it and needs location_id, and links you leave out are deleted. Send up to 100 items; an id not on the deal returns 422 exists, and nothing changes if any item is invalid. The answer lists the items in the order you sent them, while GET /deals/{deal_id}/locations orders by location_id. Each location_id must be one of your organisation's locations from GET /locations, else 422 exists. A published deal accepts it. dry_run shows the result without saving it. Emits deal_location.created, deal_location.updated and deal_location.deleted, one for each link that changed, and sends no email. Deleted links can't be restored. To change one link, use PATCH /deals/{deal_id}/locations/{id}.

The earlier version of this call took {"locations": [...]} with up to 1000 entries at /deals/{dealId}/locations. The body is now {"items": [...]} with up to 100, and each item may carry the id of the link it updates.

Path parameters

  • deal_idstring (uuid)Required#

    The deal's id, a uuid. An unknown deal, or one the token can't see, returns 404.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Request body

application/json, required

{
  "items": [
    {
      "id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8091a2b3",
      "details": "Registered office"
    },
    {
      "location_id": 77,
      "details": null
    }
  ]
}

Responses

200

The locations of the deal after the replace, in the order they were sent.

DealLocation[]
{
  "data": [
    {
      "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "location_id": 1,
      "label": "string",
      "details": "string",
      "created_at": "2026-06-12T10:00:00+00:00",
      "updated_at": "2026-06-12T10:00:00+00:00"
    }
  ]
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X PUT https://your-org-domain/kong/core/api/v2/deals/{deal_id}/locations\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "items": [
    {
      "id": "7a8b9c0d-1e2f-4a3b-8c5d-6e7f8091a2b3",
      "details": "Registered office"
    },
    {
      "location_id": 77,
      "details": null
    }
  ]
}'