Cancellations, returns and deliveries reported as facts
2026-11-15 · Breaking change · Upcoming: not yet in production
Cancelled and returned quantities are reported as facts, once each, and
PATCH /api/v1/orders/{id}/lines/{lineId}/quantities is deprecated: every response of it carries
Deprecation (RFC 9745) and Link: <this entry>; rel="deprecation".
What changed
- Report a cancellation with
POST /api/v1/orders/{id}/lines/{lineId}/cancellationsand a return, without a return case, withPOST /api/v1/orders/{id}/lines/{lineId}/returns, for example{"externalId": "rma-2291-1", "quantity": 1, "occurredAt": "2026-11-13T16:45:00+01:00"}, which gives 201 withid,orderId,orderLineId,externalId,quantity,occurredAtandrecordedAt(both UTC with microseconds). The line'scancelledandreturnedare the sums of these facts. externalId(1 to 100 characters, unique per line for cancellations and for returns; ids starting withorderex:in any case are reserved and rejected with 400) makes a retry safe: the same id with the same quantity and instant returns 200 with the fact as first reported, another quantity or time 409https://orderex.io/problems/fact-conflictwithexistingFact. The optionalIdempotency-Keyworks as onPOST /api/v1/orders.occurredAtneeds an offset and may be at most 5 minutes after the server time (else 422https://orderex.io/problems/occurred-at-in-future).- A fact that breaks a line rule is rejected with 422
line-quantity-rule-violated, as in change 4, and a return above shipped is sent again once the shipment is reported. - Facts are accepted in every order status and never move it, so an order
can show
Deliveredwhile all its lines areReturned. - On
PATCH .../quantities,cancelled,returnedandshippedmay be left out or sent with the current sums, which change nothing; any other value is rejected with 422https://orderex.io/problems/quantity-reported-as-fact, whoseerrorsnamescancelled,returnedorshippedand whosereplacedBynames the endpoint to use.orderedandinvoicedstay there. shippedis the sum of the line's shipments (change 8), reported withPOST /api/v1/orders/{id}/shipments, and a left outshippednow keeps that sum: before change 8 it meant 0. A shipped quantity is corrected by voiding the shipment withPOST /api/v1/orders/{id}/shipments/{shipmentId}/void(change 8) and reporting the right one with a newexternalId; a shipped sum from before change 8 is corrected by voiding its opening shipment.- Every existing cancelled and returned sum became one fact per kind with
externalIdorderex:opening. - Delivered quantities come from the carrier's tracking events, and
deliveredonPATCH .../quantitiesis closed the same way: a left outdeliveredkeeps the sum (it no longer means 0), the current sum changes nothing, and any other value is rejected with 422quantity-reported-as-fact, whoseerrors["delivered"]andreplacedBynamePOST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events. - Record each carrier event on a parcel of a shipment there, for example
{"externalEventId": "pn-58213-0004", "code": "Delivered", "carrierCode": "21", "occurredAt": "2026-11-18T09:12:00+01:00"}, which gives 201 withid,shipmentId,parcelId, the fields sent,occurredAtandrecordedAt(UTC with microseconds),sourceandbecameLatest.codeis one ofInfoReceived,InTransit,OutForDelivery,Delivered,DeliveryFailed,ReturnedToSenderandException, in exactly this case (else 400);carrierCodeis the carrier's own code. - The same
externalEventIdon the parcel with the same content returns 200 with the event as first recorded, other content 409fact-conflict; without an id an event is unique bycodeandoccurredAt. - The parcel's latest event is the one with the latest
occurredAt, thenrecordedAt, so a late event is kept in the history (GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events) withbecameLatest: false. - A shipment line is delivered when the latest code of every parcel of its shipment is
Delivered, and each line'squantities.deliveredis the sum over its shipments: it is derived from the parcels' latest codes, so it can fall again after a newer event that is notDelivered, such asReturnedToSender, and a newerDeliveredrestores it. A void of a shipment lowers bothshippedanddeliveredby what it held. A shipment without parcels is never delivered through tracking. - The shipment bodies show
lines[].deliveredandparcels[].latestTracking. Tracking never updates the legacydeliveryobject and never moves the order status. - Every existing delivered sum was spread over the line's shipments that are not voided, the opening shipment first, as their delivered quantity until their first tracking event; a line whose delivered was above shipped keeps it.
- The order timeline gets
orders.parcel_tracking_recorded.v1andorders.line_quantities_changed.v1withchangetracking_recorded; neither is a webhook. - Added with this change, not breaking: an optional
occurredAtonPATCH .../quantities, which becomesfactOccurredAtof the change;orders.line_returned.v1in the order timeline for every return, which is not a webhook; and the order timeline is now sorted on when a change happened (data.factOccurredAtof a line change or return, the recorded time of every other event), then on the recorded time andid, withfromandtoon the same time, so a return from yesterday reported today is listed before today's changes. Each entry'soccurredAtstays the recorded time. - The
Deprecationheader ofPATCH .../quantitiescarries the date 2027-01-01 (@1798761600), and itsLinknames this entry.
Affected operations
PATCH /api/v1/orders/{id}/lines/{lineId}/quantities, deprecatedPOST /api/v1/orders/{id}/lines/{lineId}/cancellations, newPOST /api/v1/orders/{id}/lines/{lineId}/returns, newPOST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events, newGET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events, newGET /api/v1/orders/{id},GET /api/v1/orders/{id}/shipmentsandGET /api/v1/orders/{id}/shipments/{shipmentId}, whose quantities follow the factsGET /api/v1/orders/{id}/timeline
What you do
- Report each cancellation and return once with your own id, report each shipment as in change 8,
correct a shipped quantity by voiding the shipment, and stop sending
cancelled,returnedandshippedtoPATCH .../quantities, or send the current sums. - Record each carrier event on its parcel with the carrier's event id, stop sending
deliveredtoPATCH .../quantities, or send the current sum, and read delivered quantities from the order and its shipments. - An opening shipment
orderex:openinghas no parcels, so its delivered quantity never rises: a line of an opening shipment that was not fully delivered is corrected by voiding the opening shipment, reporting it again with its parcels and recording their tracking, as for a shipped quantity.
How breaking changes are announced and how long a deprecated endpoint stays: see the versioning policy.