Inventory Holds

Create Inventory Hold

Changed on

Creates an inventory hold, which keeps the held units from being shipped.

General description

  • Currently every hold is placed on an Advance Shipping Notice (ASN): it covers products expected on the receiving. The hold must be created while the receiving's status is awaiting or arrived; a request for an in_progress or received receiving is rejected. Other kinds of holds may become available later.
  • Each item holds one product, optionally narrowed down to a single lot number and/or expiration date.
  • An item whose scope is already held, the same product with the same lot number and expiration date, is rejected, whether it is this hold or another hold on the same ASN that holds it. A wider and a narrower scope 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. A scope that was already released can be held again.
  • A single ASN can carry several holds, each identified by the returned inventory_hold_uuid.
post/v1/integrations/inventory-hold

Request

  • Base URL: https://api.shipmonk.com
  • URL: https://api.shipmonk.com/v1/integrations/inventory-hold
  • Auth: API key in header Api-Key

Request body

asnstring required

Advance Shipping Notice (ASN) number of the receiving the hold applies to. The receiving's status must be awaiting or arrived; a request for an in_progress or received receiving is rejected.

namestring required

Name of the inventory hold, shown in the ShipMonk app. Use it to tell your holds apart, e.g. by the reason for holding.

notestring nullable

Note explaining why the inventory is held. Visible in the ShipMonk app to both you and ShipMonk.

Example request

{
  "asn": "ASN-12345",
  "name": "Damaged pallet from supplier",
  "items": [
    {
      "lot": {
        "lot_number": "LOT-2025-001",
        "expiration_date": "2025-07-24"
      }
    }
  ]
}

Response

Success

inventory_hold_uuidstring required

Identifier of the created inventory hold. Use it to update or release the hold later.

Changes