Trading

/api/integration/trading — domain: Trading

The only endpoint on this surface that flows back. Everything else pushes master data in; this reports what happened to an order after Commerce handed it over.

Domain. Trading, which owns baskets and orders.

PUT /order-line-updates

Purpose. Report per-line fulfilment progress — how much has been invoiced, shipped or cancelled — so a customer can see order status without Commerce polling for it.

Request

IntegrationEnvelope<FulfilmentEnvelopeItem>.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "orderLineId": "0f8b7c2e-9a41-4f0e-9b2a-5c1d3e6f7a80",
      "orderNumber": null,
      "lineNumber": null,
      "invoicedQuantity": 10,
      "shippedQuantity": 10,
      "cancelledQuantity": 0,
      "lastUpdatedAt": "2026-08-19T04:00:00Z",
      "lastUpdatedReference": "SH-00871"
    },
    {
      "orderLineId": null,
      "orderNumber": "ORD-0000123",
      "lineNumber": 2,
      "invoicedQuantity": 0,
      "shippedQuantity": 0,
      "cancelledQuantity": 4,
      "lastUpdatedAt": "2026-08-19T04:00:00Z",
      "lastUpdatedReference": "CAN-0031"
    }
  ]
}

Field	Type	Required	Description
orderLineId	guid		Commerce's internal identifier for the order line. Preferred when the upstream system holds it
orderNumber	string		The order number Commerce issued. Used with lineNumber when orderLineId is unknown
lineNumber	int		Position of the line within the order. Used with orderNumber
invoicedQuantity	int	Yes	Units invoiced so far — a running total, not an increment
shippedQuantity	int	Yes	Units despatched so far — a running total, not an increment
cancelledQuantity	int	Yes	Units cancelled — a running total, not an increment
lastUpdatedAt	date-time		When the upstream system last changed this line. The quantities are the position as at this moment
lastUpdatedReference	string		The upstream document behind the change, for example a shipment or credit reference

Two rules that make this safe to retry

Identify a line one of two ways. Either send orderLineId, or send orderNumber and lineNumber together. The first is preferred because it cannot be ambiguous.

Quantities are totals, not deltas. Each value is the position as at lastUpdatedAt, not the change since the last message. Re-sending an identical payload is a safe no-op, and a message lost in transit is corrected by the next one rather than leaving a permanent gap.

Why there is no status field

Commerce does not store an order status. Display status is derived at read time from these three quantities against the ordered quantity — fully cancelled, fully shipped, part-shipped, invoiced, or pending.

That is why a repeated or out-of-order message changes nothing: there is no status to get stuck in the wrong state. The quantities are the truth and status falls out of them.

Charge lines — shipping and surcharge — have no fulfilment lifecycle and are skipped.

Response

One entry per line.

{
  "data": [
    { "key": "0f8b7c2e-9a41-4f0e-9b2a-5c1d3e6f7a80", "outcome": "Upserted" }
  ]
}