Changelog
Back to All

v1.028

about 2 hours ago

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.