---
agentTools:
  projectIndex: https://apidocs.shipmonk.com/llms.txt
---

# v1.028

**Inventory on an incoming ASN can be held over the API.**
Four new endpoints let you hold products expected on a receiving, change what the hold covers, release it, and list the holds of your account. A hold keeps the units from being shipped once they are received; releasing it puts them back in play.

***

## 🚀 New Endpoints

* **Create Inventory Hold** (`POST /v1/integrations/inventory-hold`) — holds the listed products of an ASN and returns the `inventory_hold_uuid` to send with the other calls. Each item holds one product, optionally narrowed down to a single lot number and/or expiration date.
* **Update Inventory Hold** (`POST /v1/integrations/inventory-hold/update`) — the `items` list is the desired state, so products missing from it are released, new ones are held and the rest is left untouched.
* **Release Inventory Hold** (`POST /v1/integrations/inventory-hold/release`) — releases the whole hold. A hold still awaiting ShipMonk review ends `cancelled` instead of `released`, and the response message says which of the two happened. The call is idempotent, so releasing an already released hold succeeds and changes nothing.
* **Inventory Holds List** (`GET /v1/integrations/inventory-holds-list`) — paginated list of the holds placed on your ASNs, newest first, with optional `asn` and `status` filters.

## 🛠 Schema & Property Updates

*None*

## 📦 New Support Schemas

* **`InventoryHoldItemInput`** and **`InventoryHoldItemLotInput`** — the `sku` and optional `lot` pair describing what a hold covers, shared by create and update.
* **`PublicApiInventoryHoldOutput`** and **`PublicApiInventoryHoldItemOutput`** — the returned hold with its identifier, type, status, name, ASN, note, creation time and items.
* **`PublicApiInventoryHoldStatus`** — `awaiting_review`, `held`, `released`, `cancelled`.
* **`PublicApiInventoryHoldType`** — `asn`, `on_demand`, `expiration`, `audit`.

## 📖 Documentation & Constraints Changes

* **Create Inventory Hold** and **Update Inventory Hold** work only until the warehouse starts receiving the shipment; afterwards the request is rejected. **Release Inventory Hold** works at any time, also once receiving has started.

* One ASN can carry several holds. An identical scope, the same product with the same lot number and expiration date, is rejected with a 400 when it is already held, whether by this hold or another one. Wider and narrower scopes can coexist, so a hold on every lot of a product and a hold on one of its lots both apply to the same units.

* The list also returns holds set up for you in the ShipMonk app, as long as they are placed on an ASN. Inventory held for other reasons, for example a quarantine on stock already in the warehouse, is not listed and cannot be changed over the API.

* In the list, an item with `sku: null` means the hold covers every product of the receiving. Such a hold is read-only over the API and can be changed only in the ShipMonk app.

* Date fields in request bodies now carry an example value in this specification, the same way timestamps already did. This affects the documentation only: order lot expiration, order cancel date, order special-requirement dates, receiving estimated delivery and receiving lot expiration.

*No endpoints, fields, or required-status were removed or changed — fully backward-compatible.*