> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory

ShipStream tracks each merchant's inventory at all times using the following statuses:

* **Expected** - Listed on open ASNs, RMAs and Other Deliveries that have not yet been received.
* **Processed** - Counted on an ASN, RMA or Other Delivery but not yet put-away.
* **Put-Away** - Has been received on an ASN, RMA or Other Delivery that has not yet been committed to the inventory. If you have auto-commit enabled this should always be 0.
* **Available** - Available for new orders. Backordered amounts are not reflected as a negative Available amount but are tracked separately as "Backordered".
* **Allocated** - Allocated to existing orders but not yet Reserved.
* **Reserved** - Reserved to a specific shelf location and waiting to be picked.
* **Picked** - Picked from the shelves but not yet packed.
* **Packed** - Packed into a shipment that has not yet shipped. Packed inventory is still in the warehouse, so it remains counted in the on-hand total until the shipment ships. Use on hand minus packed if you need the figure that excludes packed inventory.
* **Backordered** - Reserved by existing orders but not in stock. Will be automatically converted to Reserved when stock is added. Backordered quantities are not reflected in the Available amount as a negative number.
* **Advertised** - The "Available" quantity plus the virtual BOM quantity. The virtual BOM quantity is controlled by a product's "Virtual Inventory" attribute.
* **Held** - On hand but placed on hold (quarantined, damaged, expired, recalled, etc.). Held inventory remains counted in the on-hand total but is excluded from the Available quantity and cannot be allocated, picked or packed, and shipments holding it cannot be shipped manually, until the hold is released. A Lot quarantine also covers the Lot's Processed, Picked and Packed quantities, which are not stored at any Location. See [inventory.holdReasons](#inventory-holdreasons) for the reasons visible to a merchant and [inventory.holdSearch](#inventory-holdsearch) to list individual holds.

Additionally, products have two flags that can be set which will affect whether or not they are retrieved in an inventory request.

* **Status** - Enabled/Disabled - If "Disabled", the product is effectively deleted and will not appear in responses to inventory requests.
* **Visibility** - Visible/Not Visible - If "Not Visible", the product will not appear in the inventory list but may still be ordered via the Merchant Panel.

## Methods

* [inventory.list](#inventory-list)
* [inventory.lots](#inventory-lots)
* [inventory.detailed](#inventory-detailed)
* [inventory.detailed\_packaging](#inventory-detailed-packaging)
* [inventory.holdSearch](#inventory-holdsearch)
* [inventory.holdReasons](#inventory-holdreasons)

***

## Entity Properties

* [Inventory Item](#inventory-item)
* [Inventory Lot](#lot-properties)
* [Inventory Hold](#inventory-hold-properties)
* [Hold Reason](#hold-reason-properties)

***

## `inventory.list`

`inventory.list (string|array|null $skus, int|null $warehouseId, string|null $updatedSince, bool $withHeldBreakdown = false)`

Get inventory levels for one or more products by SKU. If a warehouse is not specified the sum of all warehouse inventories will be returned, otherwise the inventory levels for the specified warehouse will be returned.

Each item includes a `qty_held` quantity. When `withHeldBreakdown` is `true`, each item also includes a `qty_held_by_reason` object that breaks the held quantity down by [hold reason](#inventory-holdreasons).

### Parameters

**skus** `string | array | null`

SKUs. If not specified then inventory for all SKUs will be returned.

* `string` - Get inventory for a single product by SKU.
* `array` - Get inventory for the specified products by SKU.
* `null` - Get inventory for all products.

**warehouseId** `integer | null`

Warehouse. If not specified, returned values represent sums of all warehouses.

**updatedSince** `string | null`

Return only SKUs updated since the time specified in the format `2008-07-01T22:38:07+00:00`.

**withHeldBreakdown** `boolean` (default: false)

When `true`, each item is augmented with a `qty_held_by_reason` object keyed by parent (system) [hold reason](#inventory-holdreasons) code. Defaults to `false`, which preserves the legacy response shape and avoids the additional per-call rollup query.

### Return Value

An array of [Inventory Items](#inventory-item) or an empty array if there were no matching SKUs.

### Example Request

Get inventory for two SKUs:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.list",
        [
            ["BlueWidget-1","BlueWidget-5"]
        ]
    ]
}
```

Get all inventory:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.list"
    ]
}
```

Get all inventory for warehouse "2":

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.list",
        [
            null,
            2
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : [
        {
            "sku" : "BlueWidget-1",
            "qty_expected"    : "0.0000",
            "qty_processed"   : "0.0000",
            "qty_putaway"     : "50.0000",
            "qty_available"   : "22.0000",
            "qty_allocated"   : "5.0000",
            "qty_reserved"    : "16.0000",
            "qty_picked"      : "1.0000",
            "qty_packed"      : "3.0000",
            "qty_held"        : "4.0000",
            "qty_backordered" : "0.0000",
            "qty_advertised"  : "22.0000",
            "qty_on_hand"     : "97.0000"
        },
        {
            "sku" : "BlueWidget-5",
            "qty_expected"    : "40.0000",
            "qty_processed"   : "0.0000",
            "qty_putaway"     : "0.0000",
            "qty_available"   : "0.0000",
            "qty_allocated"   : "0.0000",
            "qty_reserved"    : "2.0000",
            "qty_picked"      : "0.0000",
            "qty_packed"      : "0.0000",
            "qty_held"        : "0.0000",
            "qty_backordered" : "5.0000",
            "qty_advertised"  : "0.0000",
            "qty_on_hand"     : "2.0000"
        }
    ]
}
```

## `inventory.lots`

`inventory.lots (null|object $filters, array $options = [])`

Retrieve list of lots by filters.

Each Lot reports quantities across its full lifecycle, including inventory that is not currently on a shelf: `qty_processed` (counted and awaiting Put-Away), `qty_picked` (picked but not yet packed) and `qty_packed` (packed but not yet shipped) are attributed to the owning Lot in addition to the on-shelf `qty_putaway`, `qty_unreserved` and `qty_reserved` quantities. A `detailed` array breaks the same quantities down per warehouse.

Hold information is returned as a structured `hold_reason` object plus a `qty_held_by_reason` rollup. See [Lot Properties](#lot-properties) for the full field list.

> [!NOTE]
>
> At the Lot level, `qty_available` is deprecated in favour of `qty_unreserved`, which is the same value under a name that matches what it measures. `qty_available` is still returned and will continue to be returned.
>
> The two names never meant the same thing: the Lot value is the physical unreserved quantity on the shelves, whereas the SKU-level `qty_available` returned by [inventory.list](#inventory-list) and [inventory.detailed](#inventory-detailed) is availability *net of open-order allocations*. Comparing them directly is the usual cause of an apparent mismatch between a SKU and its Lots. New nested structures such as `detailed` use `qty_unreserved` only; the deprecated alias exists solely at the top level of a Lot row.

### Reconciling Lots against a SKU

A Lot's quantities only ever account for inventory that could be attributed to that Lot, so for any SKU:

```
Σ (lot qty_x)  ≤  SKU qty_x
```

The difference is the **lot-less remainder** — inventory held at Locations with no Lot, or processed/picked/packed without a resolvable Lot. Totals reconcile exactly only for SKUs that are fully lot-tracked; for every other SKU, treat `Σ lots ≈ SKU qty_on_hand` as the expected relationship and the shortfall as un-attributed inventory rather than as missing stock. Attribution is never inferred: quantity that cannot be proven to belong to a Lot is deliberately left out rather than guessed.

### Parameters

**filters** `null | object`

Filters to apply for the search.

* `null` - Retrieve list of all Lots.
* `object` - Retrieve list of Lots using specified "[Search Filters](https://docs.shipstream.io/merchant-api/search-filters.md)".

**options** `null | object`

Options to apply for the search.

* `null` - No options will be applied.
* `object` - Apply specified "[Search Options](https://docs.shipstream.io/merchant-api/search-options.md)". The `limit` option is capped at `100` Lots per page; a larger value is silently reduced to `100`. Use `page` together with the returned `numPages` to retrieve the remaining results.

### Return Value

An object containing `results`, `totalCount` and `numPages`. Each entry in `results` will contain [Lot Properties](#lot-properties).

### Example Request

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.lots",
        [
            {
                "lot_id" : {
                    "in" : [1, 2]
                }
            },
            []
        ]
    ]
}
```

### Example Response

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : {
       "results": [
           {
               "lot_id": "1",
               "lot_number": "2018-07-09",
               "origination_date": "2018-07-09",
               "expiration_date": "2019-04-07",
               "is_active": "1",
               "group_value": "2018-07-09",
               "created_at": "2018-07-09T19:58:23+00:00",
               "sku": "product1",
               "name": "product 1",
               "locations": [
                   "location 1"
               ],
               "hold_reason": {
                   "code": "qc_inspection",
                   "label": "QC Inspection",
                   "display_group": "Review"
               },
               "is_on_hold": true,
               "qty_processed": "4.0000",
               "qty_putaway": "0.0000",
               "qty_unreserved": "66.0000",
               "qty_available": "66.0000",
               "qty_reserved": "0.0000",
               "qty_picked": "2.0000",
               "qty_packed": "0.0000",
               "qty_on_hand": "72.0000",
               "qty_held": "72.0000",
               "qty_held_by_reason": {
                   "qc_inspection": "72.0000"
               },
               "detailed": [
                   {
                       "warehouse_id": 1,
                       "qty_processed": "4.0000",
                       "qty_putaway": "0.0000",
                       "qty_unreserved": "66.0000",
                       "qty_reserved": "0.0000",
                       "qty_picked": "2.0000",
                       "qty_packed": "0.0000",
                       "qty_on_hand": "72.0000",
                       "qty_held": "72.0000"
                   }
               ]
           },
           {
               "lot_id": "2",
               "lot_number": "2018-07-09",
               "origination_date": "2018-07-09",
               "expiration_date": "2019-04-11",
               "is_active": "1",
               "group_value": "2018-07-09",
               "created_at": "2018-07-09T19:59:03+00:00",
               "sku": "product2",
               "name": "product 2",
               "locations": [],
               "hold_reason": null,
               "is_on_hold": false,
               "qty_processed": "0.0000",
               "qty_putaway": "0.0000",
               "qty_unreserved": "0.0000",
               "qty_available": "0.0000",
               "qty_reserved": "0.0000",
               "qty_picked": "0.0000",
               "qty_packed": "0.0000",
               "qty_on_hand": "0.0000",
               "qty_held": "0.0000",
               "qty_held_by_reason": {},
               "detailed": []
           }
       ],
       "totalCount": 2,
       "numPages": 1
   }
}
```

### Error Codes

| code | message |
| - | - |
| 102 | Unexpected error applying filters. |

## `inventory.detailed`

`inventory.detailed (string|array|null $skus, string|null $updatedSince, bool $withHeldBreakdown = false)`

Get global and per-warehouse inventory levels for one or more products by SKU.

Each item — and each per-warehouse `detailed` entry — includes a `qty_held` quantity. When `withHeldBreakdown` is `true`, each item is additionally augmented with a `qty_held_by_reason` object (held quantity grouped by parent [hold reason](#inventory-holdreasons) code) and, when user-defined sub-reasons exist, a `qty_held_by_user_reason` object that breaks each parent reason down by its user-defined child reasons. Both rollups are reported at the item level only, not per warehouse.

### Parameters

**skus** `string | array | null`

SKUs. If not specified then inventory for all SKUs will be returned.

* `string` - Get inventory for a single product by SKU.
* `array` - Get inventory for the specified products by SKU.
* `null` - Get inventory for all products.

**updatedSince** `string | null`

Return only SKUs updated since the time specified in the format `2008-07-01T22:38:07+00:00`.

**withHeldBreakdown** `boolean` (default: false)

When `true`, each item is augmented with a `qty_held_by_reason` object and, where applicable, a `qty_held_by_user_reason` object. Defaults to `false`, which preserves the legacy response shape and avoids the additional hold rollup queries.

### Return Value

An array of detailed items inventory, or an empty array if there were no matching SKUs.

### Example Request

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.detailed",
        [
            ["BlueWidget-1","BlueWidget-5"],
            "2014-07-24T18:51:18+00:00",
            true
        ]
    ]
}
```

### Example Response

The example below was requested with `withHeldBreakdown` set to `true`, so each item includes the `qty_held_by_reason` (and, where user-defined sub-reasons exist, `qty_held_by_user_reason`) rollups. With the default `false`, those two fields are omitted but `qty_held` is still present on every item and warehouse entry.

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : [
        {
            "sku": "BlueWidget-1",
            "qty_expected": "0.0000",
            "qty_processed": "0.0000",
            "qty_putaway": "0.0000",
            "qty_available": "5.0000",
            "qty_allocated": "0.0000",
            "qty_reserved": "0.0000",
            "qty_picked": "2.0000",
            "qty_packed": "0.0000",
            "qty_held": "3.0000",
            "qty_backordered": "0.0000",
            "qty_advertised": "5.0000",
            "qty_on_hand": "10.0000",
            "qty_held_by_reason": {
                "damaged": "2.0000",
                "qc_inspection": "1.0000"
            },
            "qty_held_by_user_reason": {
                "qc_inspection": {
                    "qc_lab_review": "1.0000"
                }
            },
            "detailed": [
                {
                    "warehouse_id": "1",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "5.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "2.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "3.0000",
                    "qty_advertised": "5.0000",
                    "qty_on_hand": "10.0000"
                },
                {
                    "warehouse_id": "2",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "0.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "0.0000",
                    "qty_on_hand": "0.0000"
                },
                {
                    "warehouse_id": "3",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "0.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "0.0000",
                    "qty_on_hand": "0.0000"
                }
            ]
        },
        {
            "sku": "BlueWidget-5",
            "qty_expected": "0.0000",
            "qty_processed": "0.0000",
            "qty_putaway": "0.0000",
            "qty_available": "98.0000",
            "qty_allocated": "0.0000",
            "qty_reserved": "0.0000",
            "qty_picked": "1.0000",
            "qty_packed": "0.0000",
            "qty_held": "0.0000",
            "qty_backordered": "0.0000",
            "qty_advertised": "98.0000",
            "qty_on_hand": "99.0000",
            "qty_held_by_reason": {},
            "detailed": [
                {
                    "warehouse_id": "1",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "98.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "1.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "98.0000",
                    "qty_on_hand": "99.0000"
                },
                {
                    "warehouse_id": "2",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "0.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "0.0000",
                    "qty_on_hand": "0.0000"
                },
                {
                    "warehouse_id": "3",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "0.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "0.0000",
                    "qty_on_hand": "0.0000"
                }
            ]
        }
    ]
}
```

### Error Codes

| code | message |
| - | - |
| 102 | Unexpected error applying filters. |

## `inventory.detailed_packaging`

`inventory.detailed_packaging (string|array|null $skus, string|null $updatedSince, bool $withHeldBreakdown = false)`

Get global and per-warehouse inventory levels for Packaging Features by SKU. This method is similar to `inventory.detailed` but returns only Packaging Feature types (Container, Supplies, and Infill) that can have inventory. Regular products and other Packaging Feature types are excluded from the results.

As with `inventory.detailed`, each item and warehouse entry includes a `qty_held` quantity, and the optional `withHeldBreakdown` parameter adds the item-level `qty_held_by_reason` (and `qty_held_by_user_reason`) rollups.

### Parameters

**skus** `string | array | null`

SKUs. If not specified then inventory for all Packaging Feature SKUs will be returned.

* `string` - Get inventory for a single Packaging Feature by SKU.
* `array` - Get inventory for the specified Packaging Features by SKU.
* `null` - Get inventory for all Packaging Features (Container, Supplies, and Infill).

**updatedSince** `string | null`

Return only SKUs updated since the time specified in the format `2008-07-01T22:38:07+00:00`.

**withHeldBreakdown** `boolean` (default: false)

When `true`, each item is augmented with a `qty_held_by_reason` object and, where applicable, a `qty_held_by_user_reason` object. Defaults to `false`.

### Return Value

An array of detailed Packaging Feature inventory, or an empty array if there were no matching SKUs. Only Packaging Feature types (Container, Supplies, and Infill) are included in the response.

### Example Request

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.detailed_packaging",
        [
            ["PB1688","PB16816"],
            "2014-07-24T18:51:18+00:00"
        ]
    ]
}
```

### Example Response

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : [
        {
            "sku": "PB1688",
            "qty_expected": "50.0000",
            "qty_processed": "0.0000",
            "qty_putaway": "0.0000",
            "qty_available": "150.0000",
            "qty_allocated": "0.0000",
            "qty_reserved": "0.0000",
            "qty_picked": "0.0000",
            "qty_packed": "0.0000",
            "qty_held": "0.0000",
            "qty_backordered": "0.0000",
            "qty_advertised": "150.0000",
            "qty_on_hand": "150.0000",
            "detailed": [
                {
                    "warehouse_id": "1",
                    "qty_expected": "50.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "100.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "100.0000",
                    "qty_on_hand": "100.0000"
                },
                {
                    "warehouse_id": "2",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "50.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "50.0000",
                    "qty_on_hand": "50.0000"
                }
            ]
        },
        {
            "sku": "PB16816",
            "qty_expected": "0.0000",
            "qty_processed": "0.0000",
            "qty_putaway": "0.0000",
            "qty_available": "200.0000",
            "qty_allocated": "0.0000",
            "qty_reserved": "0.0000",
            "qty_picked": "0.0000",
            "qty_packed": "0.0000",
            "qty_held": "0.0000",
            "qty_backordered": "0.0000",
            "qty_advertised": "200.0000",
            "qty_on_hand": "200.0000",
            "detailed": [
                {
                    "warehouse_id": "1",
                    "qty_expected": "0.0000",
                    "qty_processed": "0.0000",
                    "qty_putaway": "0.0000",
                    "qty_available": "200.0000",
                    "qty_allocated": "0.0000",
                    "qty_reserved": "0.0000",
                    "qty_picked": "0.0000",
                    "qty_packed": "0.0000",
                    "qty_held": "0.0000",
                    "qty_advertised": "200.0000",
                    "qty_on_hand": "200.0000"
                }
            ]
        }
    ]
}
```

### Error Codes

| code | message |
| - | - |
| 102 | Unexpected error applying filters. |

## `inventory.holdSearch`

`inventory.holdSearch (null|object $filters, array $options = [])`

Search the merchant's active and released inventory holds. Results are always scoped to the calling merchant's own inventory — no filter combination can return another merchant's holds. The response is paginated and shaped like [inventory.lots](#inventory-lots): `{ results, totalCount, numPages }`. Each result row includes structured `lot` and `reason` objects alongside the core hold fields.

For privacy, hold rows do not expose internal location identifiers or labels — including inside nested objects. The embedded `lot` object contains no location information. Identify the held inventory using `sku`, `lot.lot_number`, and `reason.code` instead.

### Parameters

**filters** `null | object`

Filters to apply to the search. Every key is optional, and unknown keys are rejected. Combine any of:

* `product_id` (integer) — holds on a specific product.
* `sku` (string) — holds on a specific SKU.
* `warehouse_id` (integer) — restrict to one warehouse. Must be a warehouse the merchant can access.
* `reason_code` (string) — exact [hold reason](#inventory-holdreasons) code. Matches that reason only; it does **not** roll child reasons up to their parent.
* `lot_id` (integer) — holds on a specific lot by internal lot ID.
* `lot_number` (string) — holds on a specific lot by lot number.
* `status` (string) — `active` (not yet released) or `released`.
* `held_after` (string) — only holds placed on or after this ISO 8601 timestamp.
* `held_before` (string) — only holds placed on or before this ISO 8601 timestamp.

The ambiguous `lot` filter is not supported — use `lot_id` or `lot_number`.

**options** `null | object`

Pagination and sorting:

* `sort_field` (string) — `held_at` (default), `released_at`, or `hold_id`.
* `sort_dir` (string) — `asc` or `desc` (default `desc`).
* `page` (integer) — 1-based page number (default `1`).
* `limit` (integer) — page size, capped at `100` (default `50`).

### Return Value

An object with `results` (an array of [Inventory Hold](#inventory-hold-properties) objects), `totalCount`, and `numPages`.

### Example Request

Active damage holds for one SKU, newest first:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.holdSearch",
        [
            {
                "sku": "BlueWidget-1",
                "reason_code": "damaged",
                "status": "active"
            },
            {
                "sort_field": "held_at",
                "sort_dir": "desc",
                "limit": 50
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : {
        "results": [
            {
                "hold_id": 4821,
                "sku": "BlueWidget-1",
                "product_name": "Blue Widget (single)",
                "lot": {
                    "lot_id": 42,
                    "lot_number": "2026-03-15",
                    "expiration_date": "2027-03-15",
                    "origination_date": "2026-03-15",
                    "group_value": null,
                    "is_active": 1,
                    "is_expired": 0,
                    "created_at": "2026-03-15T08:30:00+00:00"
                },
                "reason": {
                    "code": "damaged",
                    "label": "Damaged",
                    "display_group": "Hold"
                },
                "qty": "2.0000",
                "held_at": "2026-04-12T16:09:44+00:00",
                "released_at": null,
                "notes": "Crushed corner found during QC",
                "status": "active"
            }
        ],
        "totalCount": 1,
        "numPages": 1
    }
}
```

### Error Codes

| code | message |
| - | - |
| 101 | The Warehouse does not exist or the Merchant does not have access to the Warehouse specified. |
| 102 | Invalid or unsupported filter, sort field, status, or date range. |

## `inventory.holdReasons`

`inventory.holdReasons()`

Retrieve the list of active inventory hold reasons that are visible to the calling merchant.

### Parameters

This method takes no parameters.

### Return Value

An array of objects, each containing the [Hold Reason Properties](#hold-reason-properties).

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "inventory.holdReasons"
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : [
        { "code": "qc_inspection",    "label": "QC Inspection",            "display_group": "Hold" },
        { "code": "cycle_count",      "label": "Cycle Count",              "display_group": "Hold" },
        { "code": "damaged",          "label": "Damaged",                  "display_group": "Hold" },
        { "code": "recalled",         "label": "Recalled",                 "display_group": "Hold" },
        { "code": "expired",          "label": "Expired",                  "display_group": "Hold" },
        { "code": "near_expiry",      "label": "Near Expiry",              "display_group": "Hold" },
        { "code": "contaminated",     "label": "Contaminated",             "display_group": "Hold" },
        { "code": "bond_hold",        "label": "Customs/Bond Hold",        "display_group": "Hold" },
        { "code": "pending_disposal", "label": "Pending Disposal",         "display_group": "Hold" },
        { "code": "pending_return",   "label": "Pending Return to Vendor", "display_group": "Hold" }
    ]
}
```

## Entity Properties

### Inventory Item

**sku** `string`

A unique identifier for a product. The SKU does appear on the packing slip. It is recommended that this be human-readable and end with a per-pack quantity to facilitate proper receiving. For example, a single blue widget may be "BlueWidget-1" and a pack of 5 blue widgets may be "BlueWidget-5". Maximum character length is 64.

**qty\_expected** `integer`

The "Expected" quantity.

**qty\_processed** `integer`

The "Processed" quantity.

**qty\_putaway** `integer`

The "Put-Away" quantity.

**qty\_available** `integer`

The "Available" quantity.

**qty\_allocated** `integer`

The "Allocated" quantity.

**qty\_reserved** `integer`

The "Reserved" quantity.

**qty\_picked** `integer`

The "Picked" quantity — picked from the shelves but not yet packed.

**qty\_packed** `integer`

The "Packed" quantity — packed into shipments that have not yet shipped. This inventory is still in the warehouse and is included in `qty_on_hand` until the shipment ships. Subtract `qty_packed` from `qty_on_hand` if you need the on-hand figure that excludes packed inventory.

**qty\_held** `integer`

The "Held" quantity — inventory placed on hold (quarantined, damaged, expired, recalled, etc.), including held packed inventory. Held inventory stays counted in `qty_on_hand` but is excluded from `qty_available` and cannot be allocated, picked, or packed until the hold is released.

**qty\_backordered** `integer`

The "Backordered" quantity. This quantity will not be present for single-warehouse requests since backordered amounts are not apportioned to specific warehouses.

**qty\_advertised** `integer`

The "Advertised" quantity. This is the "Available" quantity plus the virtual BOM quantity. The virtual BOM quantity is controlled by a product's "Virtual Inventory" attribute.

**qty\_on\_hand** `integer`

The total physical quantity currently in the warehouse, including packed inventory that has not yet shipped and held inventory exactly once. `qty_held` is a diagnostic subset of this total and must not be added to `qty_on_hand`; held Put-Away and Reserved quantities are already included in their corresponding lifecycle quantities.

**qty\_held\_by\_reason** `object`

Present only when a request is made with `withHeldBreakdown` set to `true`. An object that breaks `qty_held` down by parent (system) [hold reason](#inventory-holdreasons) code, e.g. `{ "damaged": "2.0000", "qc_inspection": "1.0000" }`. Reasons with no held quantity are omitted; an empty object means nothing is held.

**qty\_held\_by\_user\_reason** `object`

Present only on `inventory.detailed` / `inventory.detailed_packaging` requests made with `withHeldBreakdown` set to `true`, and only when user-defined sub-reasons are in use. A nested object keyed by parent reason code, each mapping to its user-defined child reason codes and their held quantities, e.g. `{ "qc_inspection": { "qc_lab_review": "1.0000" } }`.

### Lot Properties

**lot\_id** `integer`

The internal lot ID.

**is\_active** `integer`

Flag whether lot is active.

**sku** `string`

The "SKU" property.

**name** `string`

The "Name" property.

**lot\_number** `string`

The "Lot Number" property.

**expiration\_date** `string`

The "Expiration Date" property.

**origination\_date** `string`

The "Origination Date" property.

**group\_value** `string`

The "Group Value" property.

**created\_at** `string`

The "Created At" property in ISO 8601 format.

**locations** `array`

A list of locations.

**hold\_reason** `object | null`

A [Hold Reason](#hold-reason-properties) object describing the quarantine placed on the lot itself, or `null` when the lot is not quarantined. Fields: `code`, `label`, `display_group`.

An applied reason keeps being reported even if it is later deactivated or hidden from the merchant — visibility and activation changes affect new selections only. A lot may be `is_on_hold` with a `null` `hold_reason` when the hold is on a Location rather than on the lot; in that case use `qty_held_by_reason` for the reasons involved.

**is\_on\_hold** `boolean`

`true` when the lot itself is quarantined **or** any Location holding the lot has an active (unreleased) hold, otherwise `false`.

**qty\_processed** `string`

The "Processed" quantity attributed to this lot — counted on a Delivery but not yet put away, so it is not present at any Location.

**qty\_putaway** `string`

The "Put-Away" quantity.

**qty\_unreserved** `string`

The quantity at the lot's Locations that is not reserved and not held.

**qty\_available** `string`

*Deprecated — use `qty_unreserved` instead.* An alias returning the same value.

**qty\_reserved** `string`

The "Reserved" quantity.

**qty\_held** `string`

All held quantity attributed to the lot. This includes the held quantity at its Locations and, when the lot itself is quarantined, its off-shelf `qty_processed`, `qty_picked` and `qty_packed` quantities. `qty_held` can therefore exceed the quantity visible across the lot's Locations. It is a diagnostic subset of `qty_on_hand` and must not be added to it.

While a quarantined lot has a positive picked quantity, Packing, Shipping and Manifest completion are blocked for the affected shipments until the quarantine is released. While it has a positive packed quantity, manually shipping the affected shipments, scanning their packages onto a manifest, and sealing or loading a manifest that contains them are refused until the quarantine is released.

**qty\_picked** `string`

The "Picked" quantity attributed to this lot — picked from the shelves but not yet packed, so it is not present at any Location.

**qty\_packed** `string`

The "Packed" quantity attributed to this lot — packed into shipments that have not yet shipped, so it is not present at any Location but is still in the warehouse.

**qty\_on\_hand** `string`

The total quantity attributed to the lot that remains in the warehouse — on-shelf quantities plus `qty_processed`, `qty_picked` and `qty_packed` — counting held inventory exactly once.

**qty\_held\_by\_reason** `object`

An object breaking `qty_held` down by parent (system) [hold reason](#inventory-holdreasons) code, e.g. `{ "damaged": "2.0000" }`. User-defined sub-reasons are rolled up to their parent code. Reasons with no held quantity are omitted; an empty object means nothing is held.

This rollup is reported at the lot level only, not per warehouse — the `detailed` entries carry a `qty_held` total for each warehouse but no per-reason split.

**detailed** `array`

Per-warehouse breakdown of the lot's quantities, restricted to warehouses the merchant has access to. Each entry contains:

* `warehouse_id` (integer) — the warehouse ID.
* `qty_processed`, `qty_putaway`, `qty_unreserved`, `qty_reserved`, `qty_held`, `qty_picked`, `qty_packed`, `qty_on_hand` (string) — the same quantities as above, scoped to that warehouse. There is no per-warehouse `qty_held_by_reason`; the reason breakdown is lot-level only.

Warehouses with no quantity for the lot are omitted, so the array is empty for a lot with no remaining inventory. The top-level quantities are the sums of these entries.

### Inventory Hold Properties

Returned by [inventory.holdSearch](#inventory-holdsearch). For privacy, hold rows do not include any location identifier or label — including inside nested objects.

**hold\_id** `integer`

The internal hold ID.

**sku** `string | null`

The SKU of the held product, or `null` if it cannot be resolved.

**product\_name** `string | null`

The name of the held product, or `null` if it cannot be resolved.

**lot\_number** `string | null`

*Deprecated — use `lot.lot_number` instead.* The lot number of the held inventory, or `null` when the hold is not lot-specific.

**reason\_code** `string | null`

*Deprecated — use `reason.code` instead.* The [hold reason](#inventory-holdreasons) code for this hold.

**reason\_label** `string | null`

*Deprecated — use `reason.label` instead.* The human-readable hold reason label as configured in the merchant's account.

**lot** `object | null`

A subset of [Lot Properties](#lot-properties) for the held lot, or `null` when the hold is not lot-specific or the lot entity no longer exists. Contains no location information, quantity rollups, or product fields. Fields:

* `lot_id` (integer) — the internal lot ID.
* `lot_number` (string | null) — the lot number.
* `expiration_date` (string | null) — the expiration date.
* `origination_date` (string | null) — the origination date.
* `group_value` (string | null) — the group value.
* `is_active` (integer) — flag whether the lot is active.
* `is_expired` (integer) — flag whether the lot is expired (snapshot value, as last computed).
* `created_at` (string | null) — when the lot was created.

**reason** `object | null`

A [Hold Reason](#hold-reason-properties) object for this hold, or `null` when no reason is associated. Fields: `code`, `label`, `display_group`.

**qty** `string`

For an active Location Hold, the Location's current held quantity. This value changes as inventory enters or leaves the held Location. Released Holds and Lot-level sentinel records without a Location return `0.0000`.

**held\_at** `string`

When the hold was placed, in ISO 8601 format.

**released\_at** `string | null`

When the hold was released, in ISO 8601 format, or `null` if the hold is still active.

**notes** `string | null`

Free-text notes recorded when the hold was placed, or `null`.

**status** `string`

`active` when `released_at` is `null`, otherwise `released`.

### Hold Reason Properties

**code** `string`

The stable machine-readable identifier for the reason. Use this value when calling other endpoints that accept a `reason_code`.

**label** `string`

The human-readable label for the reason as configured in the merchant's account.

**display\_group** `string`

The bucket the reason is grouped under in the UI. Built-in groups are `Hold`, `Review`, `Expired`, and `Unsellable`; user-defined reasons may use any text up to 25 characters.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.