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 withLocation,id,statusReported,shippedAtandrecordedAt(both UTC with microseconds),source,warnings, the lines and the parcels with theirid. - Each line's
quantities.shippedis the sum of its shipments, andlineStatusandquantities.remainingfollow. - The whole shipment is rejected with 422
line-quantity-rule-violated, whoselinesnames every breaking line, when a line would ship more than ordered minus cancelled; with 422https://orderex.io/problems/shipment-node-unknownwhennodeIdis not in your node register; and with 422https://orderex.io/problems/shipment-line-not-on-orderwhen a line is not a line of the order. A deactivated node is accepted withwarnings["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 409fact-conflictwithexistingFact, so a corrected shipment needs a new id. The optionalIdempotency-Keyworks as onPOST /api/v1/orders.- Read them with
GET /api/v1/orders/{id}/shipmentsandGET /api/v1/orders/{id}/shipments/{shipmentId}; every shipped sum that existed before this change became one opening shipment per order withexternalIdorderex:opening,sourcemigration,nodeIdnulland no parcels. - A shipment is accepted in every order status and never moves it, so no
order.shippedwebhook follows from a shipment; move the order status yourself as before. - Each shipment adds
orders.shipment_reported.v1and oneorders.line_quantities_changed.v1per line to the order timeline, sorted onshippedAt; 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 withshipmentId,orderId,reason,occurredAtandrecordedAt: the shipment is kept withstatusVoidedand itsvoid, its lines'quantities.shippedfall by its quantities andquantities.deliveredby what it delivered (change 7), and a void that would bring shipped below returned is rejected with 422line-quantity-rule-violated. - A shipment is voided once: the same reason and instant return 200 with the first void, another
409
fact-conflictwithexistingFact. Each void addsorders.shipment_voided.v1and oneorders.line_quantities_changed.v1per line to the timeline, sorted on the void'soccurredAt; neither is a webhook. PATCH /api/v1/orders/{id}/deliveryis closed: every request is rejected with 422https://orderex.io/problems/endpoint-closed, whosereplacedBynamesPOST /api/v1/orders/{id}/shipments, withDeprecationandLink: <this entry>; rel="deprecation", and nothing is read or changed.deliveryis still returned byGET /api/v1/orders/{id}as it was stored and still accepted byPOST /api/v1/orders, as legacy: it never changes a shipped quantity, and tracking numbers of shipments are not added to it.- The
Deprecationheader ofPATCH .../deliverycarries the date 2027-01-01 (@1798761600), and itsLinknames this entry.
Affected operations
POST /api/v1/orders/{id}/shipments, newGET /api/v1/orders/{id}/shipments, newGET /api/v1/orders/{id}/shipments/{shipmentId}, newPOST /api/v1/orders/{id}/shipments/{shipmentId}/void, newPATCH /api/v1/orders/{id}/delivery, closedGET /api/v1/orders/{id}, whose shipped quantities are the sums of the shipmentsGET /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 ofdelivery.
How breaking changes are announced and how long a deprecated endpoint stays: see the versioning policy.