Skip to main content
GET
/
v1
/
inventory
/
holds
List / search inventory holds
curl --request GET \
  --url https://{base_url_domain}/api/global/v1/inventory/holds \
  --header 'Authorization: Bearer <token>'
{
  "collection": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next": "<string>",
  "previous": "<string>",
  "meta": {
    "processing_time": 0.2525252525,
    "cursor_start": 123,
    "cursor_end": 123,
    "count": 123
  }
}

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.

Query Parameters

​
filter
string[]

Using the filtering syntax, you may filter the results using the following fields:

  • id — hold_id
  • merchant_id
  • warehouse_id
  • product_id
  • location_id
  • lot_id
  • lot_number
  • reason_code — exact match (does NOT roll up to parent)
  • held_at — supports {from:...}, {to:...} range syntax
  • status — active or released (only eq and in operators supported)
​
sort
string

Default sort is descending by id (sort=-id) — PRIMARY-key backed and chronologically equivalent to held_at for unreleased rows under the canonical insert path. Pass sort=-held_at explicitly if your dataset includes backfilled or timestamp-corrected rows where insert order diverges from held_at.

Using the sorting syntax, the following fields are available for sorting:

  • id
  • held_at
​
fields:merchant
enum<string>[]

Specify additional fields of the Merchant object to be included in the response. See the selecting fields page for more information.

Available options:
basic,
all,
code,
name,
status,
created_at,
updated_at,
brands,
default_brand,
custom_fields
​
fields:warehouse
enum<string>[]

Specify additional fields of the Warehouse object to be included in the response.

Available options:
basic,
all,
id,
name,
is_active,
abbreviation
​
fields:product
enum<string>[]

Specify additional fields of the Product or Packaging* object to be included in the response.

Available options:
basic,
all,
created_at,
updated_at,
container_options,
supplies_options,
data_collection_options,
instruction_options,
infill_options,
vendor_sku,
external_id,
barcodes,
goods_type,
is_available,
is_visible,
weight,
dimensions,
volume,
inventory,
export,
regulated_goods,
packaging,
custom_fields
​
fields:location
enum<string>[]

Specify additional fields of the Location object to be included in the response.

Available options:
basic,
all,
label,
priority,
qty_on_hand,
qty_putaway,
qty_unreserved,
qty_reserved,
qty_locked,
is_temp,
is_pickable,
is_type_auto,
created_at,
updated_at,
last_cyclecount_at,
lot,
product,
rack,
location_type
​
fields:lot
enum<string>[]

Specify additional fields of the Lot object to be included in the response.

Available options:
basic,
all,
id,
lot_number,
origination_date,
expiration_date,
is_expired,
is_active,
lot_number_input,
expiration_input,
sort_value,
days_until_expiration,
sort_direction,
group_value,
created_at,
updated_at,
created_by,
lot_type,
product
​
fields:held_by
enum<string>[]

Specify additional fields of the Requester object (the entity that placed the hold) to be included in the response. See the selecting fields page for more information.

Available options:
all
​
fields:released_by
enum<string>[]

Specify additional fields of the Requester object (the entity that released the hold) to be included in the response. See the selecting fields page for more information.

Available options:
all
​
count
integer

If specified as 1, the meta.count property of the response will be present and populated with the total count of items matching the query before any paging is applied. This is not included by default to improve performance in some edge cases and is not required to perform paging using the next property of the response. See paging parameters for more information.

Required range: 0 <= x <= 1
​
cursor_end
integer

A cursor for use in pagination which defines the last id of the next page of results, non-inclusive. See paging parameters for more information on paging.

​
cursor_start
integer

A cursor for use in pagination which defines the starting id of the next page of results. See paging parameters for more information on paging.

​
limit
integer
default:100

A limit on the number of objects to be returned.

Required range: 1 <= x <= 1000
Example:

100

Response

List of Hold objects.

​
collection
Hold · object[]

A list of Hold objects.

​
has_more
boolean

True if the collection has more items on the next page. Use the "next" link to retrieve the next page of results.

​
next
string | null

The resource path for the next page of results if any are expected.

​
previous
string | null

The resource path for the previous page of results if any are expected.

​
meta
object

Additional metadata pertaining to the response.