Skip to main content

Shipments with lines and parcels, delivery endpoint closed

2026-11-15 · Breaking change · Upcoming: not yet in production

Shipments are reported with their lines and parcels, and PATCH /api/v1/orders/{id}/delivery is closed.

What changed

  • Report every shipment that leaves one of your nodes once with POST /api/v1/orders/{id}/shipments, for example {"externalId": "wms-58213", "nodeId": "7b1e...", "shippedAt": "2026-11-16T14:05:00+01:00", "lines": [{"orderLineId": "9e8d...", "quantity": 1}], "parcels": [{"trackingNumber": "00370712345678901234", "carrier": "Example Freight"}]}, which gives 201 with Location, id, status Reported, shippedAt and recordedAt (both UTC with microseconds), source, warnings, the lines and the parcels with their id.
  • Each line's quantities.shipped is the sum of its shipments, and lineStatus and quantities.remaining follow.
  • The whole shipment is rejected with 422 line-quantity-rule-violated, whose lines names every breaking line, when a line would ship more than ordered minus cancelled; with 422 https://orderex.io/problems/shipment-node-unknown when nodeId is not in your node register; and with 422 https://orderex.io/problems/shipment-line-not-on-order when a line is not a line of the order. A deactivated node is accepted with warnings ["inactive_node"].
  • externalId (1 to 100 characters; orderex: is reserved) is unique per order, also after the shipment is voided: the same id with the same node, instant, lines and parcels returns 200 with the shipment as first reported, any other content 409 fact-conflict with existingFact, so a corrected shipment needs a new id. The optional Idempotency-Key works as on POST /api/v1/orders.
  • Read them with GET /api/v1/orders/{id}/shipments and GET /api/v1/orders/{id}/shipments/{shipmentId}; every shipped sum that existed before this change became one opening shipment per order with externalId orderex:opening, source migration, nodeId null and no parcels.
  • A shipment is accepted in every order status and never moves it, so no order.shipped webhook follows from a shipment; move the order status yourself as before.
  • Each shipment adds orders.shipment_reported.v1 and one orders.line_quantities_changed.v1 per line to the order timeline, sorted on shippedAt; neither is a webhook.
  • A shipment reported by mistake is voided with POST /api/v1/orders/{id}/shipments/{shipmentId}/void, for example {"reason": "Reported twice by the WMS", "occurredAt": "2026-11-16T15:10:00+01:00"}, which gives 201 with shipmentId, orderId, reason, occurredAt and recordedAt: the shipment is kept with status Voided and its void, its lines' quantities.shipped fall by its quantities and quantities.delivered by what it delivered (change 7), and a void that would bring shipped below returned is rejected with 422 line-quantity-rule-violated.
  • A shipment is voided once: the same reason and instant return 200 with the first void, another 409 fact-conflict with existingFact. Each void adds orders.shipment_voided.v1 and one orders.line_quantities_changed.v1 per line to the timeline, sorted on the void's occurredAt; neither is a webhook.
  • PATCH /api/v1/orders/{id}/delivery is closed: every request is rejected with 422 https://orderex.io/problems/endpoint-closed, whose replacedBy names POST /api/v1/orders/{id}/shipments, with Deprecation and Link: <this entry>; rel="deprecation", and nothing is read or changed.
  • delivery is still returned by GET /api/v1/orders/{id} as it was stored and still accepted by POST /api/v1/orders, as legacy: it never changes a shipped quantity, and tracking numbers of shipments are not added to it.
  • The Deprecation header of PATCH .../delivery carries the date 2027-01-01 (@1798761600), and its Link names this entry.

Affected operations

  • POST /api/v1/orders/{id}/shipments, new
  • GET /api/v1/orders/{id}/shipments, new
  • GET /api/v1/orders/{id}/shipments/{shipmentId}, new
  • POST /api/v1/orders/{id}/shipments/{shipmentId}/void, new
  • PATCH /api/v1/orders/{id}/delivery, closed
  • GET /api/v1/orders/{id}, whose shipped quantities are the sums of the shipments
  • GET /api/v1/orders/{id}/timeline

What you do

  • Report each shipment once with your own id, its node, lines and parcels.
  • Void a shipment that was reported by mistake and report the right one with a new id.
  • Stop calling PATCH .../delivery, and read tracking numbers from the shipments instead of delivery.

How breaking changes are announced and how long a deprecated endpoint stays: see the versioning policy.