Skip to main content
POST
/
v1
/
inventory
/
holds
/
location
Place location-level Hold
curl --request POST \
  --url https://{base_url_domain}/api/global/v1/inventory/holds/location \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "location_id": 6,
  "reason_code": "damaged",
  "qty": 5,
  "notes": "Damaged at receiving"
}
'
{
  "resource": {
    "type": "Hold",
    "id": 142,
    "qty": 12,
    "held_at": "2026-04-28T14:32:00Z",
    "status": "active",
    "merchant": {
      "type": "Merchant",
      "id": 4
    },
    "warehouse": {
      "type": "Warehouse",
      "id": 123
    },
    "product": {
      "id": 123
    },
    "location": {
      "type": "Location",
      "id": 42
    },
    "lot": {
      "type": "Lot",
      "id": 54
    },
    "reason": {
      "code": "damaged",
      "label": "Damaged",
      "parent_code": "damaged"
    },
    "held_by": {
      "type": "Requester",
      "id": 3
    },
    "released_at": null,
    "released_by": {
      "type": "Requester",
      "id": 3
    },
    "notes": "Damaged in receiving",
    "updated_at": "2026-04-28T14:32:00Z"
  }
}

Authorizations

ā€‹
Authorization
string
header
required

Generate a JWT access token through a Custom Global Integration and provide it with each request in the Authorization header prefixed with "Bearer" and then a single space.

Body

application/json
ā€‹
location_id
integer<int64>
required

Target location.

Example:

6

ā€‹
reason_code
string
required

Hold reason code (system or user-defined).

Example:

"damaged"

ā€‹
qty
number<float>
required

Quantity to hold (must be > 0 and equal to the location's full holdable qty). Partial holds are not currently supported.

Example:

5

ā€‹
notes
string | null

Free-form notes.

Example:

"Damaged at receiving"

Response

Hold placed.

ā€‹
resource
Hold Ā· object

An inventory hold record. Cross-merchant view (Global API surface).

Releasing cascaded holds: when holdLot is called with cascade_bom=true, free the cascade tree by releasing each child via POST /holds/{id}/release, using origin.created_origin_hold_ids āˆŖ cascade.child_hold_ids from the original holdLot response.

Do not include origin.root_hold_ids blindly in the release set ā€” those may include pre-existing roots from a prior cascadeLotHold call that this call attached children to, and releasing them would also release siblings the current caller did not place.