The order lifecycle
This guide continues the example order from Getting started, where one of
the two T-shirts was shipped with the delivery. Here the second T-shirt is cancelled, and the shipped
one is delivered and returned. After each step you see what the T-shirt line's lineStatus
becomes.
The commands use the shell variables from Getting started:
| Variable | Where you get it |
|---|---|
ORDEREX_API_KEY | Your API key, step 1 |
ORDER_ID and TSHIRT_LINE_ID | The order's id and the T-shirt line's id, step 4 |
SHIPMENT_ID and PARCEL_ID | The shipment's id and its parcel's id, step 5 |
The steps at a glance
| Step | Call | T-shirt line after it |
|---|---|---|
| Where Getting started leaves it | POST /api/v1/orders/{id}/shipments | PartiallyShipped, 1 of 2 shipped |
| Cancel the second T-shirt | POST /api/v1/orders/{id}/lines/{lineId}/cancellations | Shipped, nothing remaining |
| The carrier delivers the parcel | POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events | Delivered |
| The customer returns the T-shirt | POST /api/v1/orders/{id}/lines/{lineId}/returns | Returned |
| Void a shipment reported by mistake | POST /api/v1/orders/{id}/shipments/{shipmentId}/void | Back to what it was before the shipment |
OrderEx derives lineStatus from the line's quantities after every fact, in this order:
Cancelledwhen all of the ordered quantity is cancelled.Returnedwhen everything shipped has been returned, andPartiallyReturnedwhen some of it has.Deliveredwhen all of the quantity that is not cancelled is delivered.Shippedwhen all of it is shipped, andPartiallyShippedwhen some of it is.Openotherwise.
The shipping line was shipped in the same shipment, so it is Shipped and becomes Delivered with
the parcel. The return below is for the T-shirt only.
What you do
1. Cancel the second T-shirt
The second T-shirt is out of stock, and your ERP cancels it.
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/lines/$TSHIRT_LINE_ID/cancellations" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"externalId": "erp-cancel-1042-1", "occurredAt": "2026-11-16T16:30:00+01:00", "quantity": 1}'
The line's quantities.cancelled becomes 1 and quantities.remaining 0. Everything that is not
cancelled has left the warehouse, so the line becomes Shipped. You can cancel at most what is
ordered and not yet shipped, or OrderEx answers 422 line-quantity-rule-violated with the rule in
rules, here cancelled-exceeds-ordered-minus-shipped.
2. Record the delivery
Your carrier integration reports what happens to each parcel. When the latest event of every parcel
in a shipment is Delivered, the shipment's lines count as delivered.
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/parcels/$PARCEL_ID/tracking-events" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"externalEventId": "ef-58213-0004", "code": "Delivered", "carrierCode": "21", "occurredAt": "2026-11-18T09:12:00+01:00"}'
The T-shirt line and the shipping line become Delivered. code is one of seven values, written
exactly like this:
| Code | Meaning |
|---|---|
InfoReceived | The carrier has the shipment's details |
InTransit | The parcel is on its way |
OutForDelivery | The parcel is out for delivery |
Delivered | The parcel is delivered |
DeliveryFailed | A delivery attempt failed |
ReturnedToSender | The parcel is on its way back |
Exception | Something else went wrong |
carrierCode is the carrier's own code, as free text. The parcel's latest event is the one with the
latest occurredAt. An event that arrives late is kept with becameLatest: false and changes
nothing else, and a newer event that is not Delivered lowers the delivered quantity again. Read a
parcel's history with GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events.
3. Report the return
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/lines/$TSHIRT_LINE_ID/returns" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"externalId": "rma-2291-1", "occurredAt": "2026-11-18T16:45:00+01:00", "quantity": 1}'
The T-shirt line becomes Returned, since everything shipped has come back. You can return at most
what is shipped: report the shipment first, or OrderEx answers 422 line-quantity-rule-violated
with returned-exceeds-shipped.
Void a shipment reported by mistake
A fact is never edited. When your warehouse system reported a shipment on the wrong order, or with
the wrong quantity, void it with a reason and report the right one with a new externalId, as in
step 5 of Getting started.
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/shipments/$SHIPMENT_ID/void" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason": "Reported on the wrong order by the WMS", "occurredAt": "2026-11-16T15:10:00+01:00"}'
- The shipment is kept with the status
Voidedand its reason, so you can still read it. - Each of its lines' shipped and delivered quantities fall by what the shipment shipped and
delivered, and
lineStatusfollows. - A void that would leave less shipped than returned gives 422
line-quantity-rule-violated, and nothing changes. In the example,wms-58213can be voided only before the return is reported.
The order status moves only when you move it
None of the calls above change the order's status. Move it yourself along your status flow:
curl -sS -X PATCH "https://api.orderex.se/api/v1/orders/$ORDER_ID/status" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "Pending"}'
OrderEx answers 204 No Content. A status or a transition your flow does not have gives 422
order-status-change-rejected with the reason in detail.
Endpoints you should not use
| Endpoint | State | Use instead |
|---|---|---|
PATCH /api/v1/orders/{id}/lines/{lineId}/quantities | Deprecated. Still replaces ordered and invoiced; any other changed quantity gives 422 quantity-reported-as-fact | The cancellation, shipment, tracking and return calls |
PATCH /api/v1/orders/{id}/delivery | Closed, answers 422 endpoint-closed | POST /api/v1/orders/{id}/shipments and tracking events |
PATCH /api/v1/orders/{id}/lines/{lineId}/status | Closed, answers 422 endpoint-closed | Nothing: lineStatus is derived from the facts |
A closed endpoint's problem names what replaces it in replacedBy. All three answer with the
Deprecation and Link headers that the versioning policy describes.
Next
Payment facts reports the rest of the money on the same order: the authorization at checkout, the release for the cancelled T-shirt and the refund for the returned one.