Inventory

/api/integration/inventory — domain: Inventory

PUT /

Purpose. Push stock positions per SKU: what is on hand at each location, what is on its way, and which reservations the upstream system now considers settled.

Domain. Inventory, which owns stock levels and the reservations held against them during checkout.

Request

IntegrationEnvelope<InventoryEnvelopeDto>.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "sku": "SHIRT-BLK-M",
      "stockOnHand": [
        {
          "locationCode": "SYD",
          "quantity": 260
        },
        {
          "locationCode": "MEL",
          "quantity": 152
        }
      ],
      "incomingStock": [
        {
          "locationCode": "SYD",
          "externalReference": "PO-77321",
          "expectedDate": "2026-09-14",
          "quantity": 500
        }
      ],
      "reservationIdentifiers": [
        "ORD-0000123"
      ]
    }
  ]
}

Field	Type	Required	Description
sku	string	Yes	The natural key. Must match a SKU sent to Catalogue
stockOnHand[]	array		Current physical stock, one entry per location
incomingStock[]	array		Expected deliveries, one entry per delivery
reservationIdentifiers[]	array of string		Reservations the upstream system has now absorbed — see below

stockOnHand[]

Field	Type	Required	Description
locationCode	string	Yes	Warehouse or location identifier
quantity	int	Yes	Units available at that location. Whole units only

incomingStock[]

Field	Type	Required	Description
locationCode	string	Yes	Where the delivery is expected
externalReference	string	Yes	The upstream reference for the delivery, typically a purchase order. Part of the key
expectedDate	date	Yes	When it is expected to arrive. Date only, no time
quantity	int	Yes	Units expected. Whole units only

Both child collections are snapshots. Send the complete set for the SKU. A location present in Commerce but absent from the payload is removed — including a location dropping to zero, which should be sent as an explicit zero or omitted deliberately, not left to chance.

incomingStock is keyed on locationCode plus externalReference, so two expected deliveries into the same warehouse are distinct rows.

What reservationIdentifiers is for

While a customer is checking out, Commerce reserves stock so two buyers cannot take the last unit. Once the upstream system has the order and its own stock reflects it, the reservation is redundant — listing its identifier here releases it.

Omitting the field leaves existing reservations untouched, which is the safe default.

Response

One entry per SKU, keyed by sku.

{
  "data": [
    { "key": "SHIRT-BLK-M", "outcome": "Upserted" }
  ]
}