Hoppa till huvudinnehåll

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}/cancellations and a return, without a return case, with POST /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 with id, orderId, orderLineId, externalId, quantity, occurredAt and recordedAt (both UTC with microseconds). The line's cancelled and returned are the sums of these facts.
  • externalId (1 to 100 characters, unique per line for cancellations and for returns; ids starting with orderex: 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 409 https://orderex.io/problems/fact-conflict with existingFact. The optional Idempotency-Key works as on POST /api/v1/orders.
  • occurredAt needs an offset and may be at most 5 minutes after the server time (else 422 https://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 Delivered while all its lines are Returned.
  • On PATCH .../quantities, cancelled, returned and shipped may be left out or sent with the current sums, which change nothing; any other value is rejected with 422 https://orderex.io/problems/quantity-reported-as-fact, whose errors names cancelled, returned or shipped and whose replacedBy names the endpoint to use. ordered and invoiced stay there.
  • shipped is the sum of the line's shipments (change 8), reported with POST /api/v1/orders/{id}/shipments, and a left out shipped now keeps that sum: before change 8 it meant 0. A shipped quantity is corrected by voiding the shipment with POST /api/v1/orders/{id}/shipments/{shipmentId}/void (change 8) and reporting the right one with a new externalId; 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 externalId orderex:opening.
  • Delivered quantities come from the carrier's tracking events, and delivered on PATCH .../quantities is closed the same way: a left out delivered keeps the sum (it no longer means 0), the current sum changes nothing, and any other value is rejected with 422 quantity-reported-as-fact, whose errors["delivered"] and replacedBy name POST /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 with id, shipmentId, parcelId, the fields sent, occurredAt and recordedAt (UTC with microseconds), source and becameLatest. code is one of InfoReceived, InTransit, OutForDelivery, Delivered, DeliveryFailed, ReturnedToSender and Exception, in exactly this case (else 400); carrierCode is the carrier's own code.
  • The same externalEventId on the parcel with the same content returns 200 with the event as first recorded, other content 409 fact-conflict; without an id an event is unique by code and occurredAt.
  • The parcel's latest event is the one with the latest occurredAt, then recordedAt, so a late event is kept in the history (GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events) with becameLatest: false.
  • A shipment line is delivered when the latest code of every parcel of its shipment is Delivered, and each line's quantities.delivered is the sum over its shipments: it is derived from the parcels' latest codes, so it can fall again after a newer event that is not Delivered, such as ReturnedToSender, and a newer Delivered restores it. A void of a shipment lowers both shipped and delivered by what it held. A shipment without parcels is never delivered through tracking.
  • The shipment bodies show lines[].delivered and parcels[].latestTracking. Tracking never updates the legacy delivery object 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.v1 and orders.line_quantities_changed.v1 with change tracking_recorded; neither is a webhook.
  • Added with this change, not breaking: an optional occurredAt on PATCH .../quantities, which becomes factOccurredAt of the change; orders.line_returned.v1 in the order timeline for every return, which is not a webhook; and the order timeline is now sorted on when a change happened (data.factOccurredAt of a line change or return, the recorded time of every other event), then on the recorded time and id, with from and to on the same time, so a return from yesterday reported today is listed before today's changes. Each entry's occurredAt stays the recorded time.
  • The Deprecation header of PATCH .../quantities carries the date 2027-01-01 (@1798761600), and its Link names this entry.

Affected operations

  • PATCH /api/v1/orders/{id}/lines/{lineId}/quantities, deprecated
  • POST /api/v1/orders/{id}/lines/{lineId}/cancellations, new
  • POST /api/v1/orders/{id}/lines/{lineId}/returns, new
  • POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events, new
  • GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events, new
  • GET /api/v1/orders/{id}, GET /api/v1/orders/{id}/shipments and GET /api/v1/orders/{id}/shipments/{shipmentId}, whose quantities follow the facts
  • GET /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, returned and shipped to PATCH .../quantities, or send the current sums.
  • Record each carrier event on its parcel with the carrier's event id, stop sending delivered to PATCH .../quantities, or send the current sum, and read delivered quantities from the order and its shipments.
  • An opening shipment orderex:opening has 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.