The order lifecycle
This guide follows the example order from Getting started after checkout.
One of the two T-shirts is cancelled, the other is shipped, delivered and returned. After each step
you see what the T-shirt line's lineStatus becomes.
The commands use these shell variables. Set them from the responses as you go.
| Variable | Where you get it |
|---|---|
ORDEREX_API_KEY | Your API key |
ORDER_ID | orderId when you create the order |
TSHIRT_LINE_ID | The id of the T-shirt line in lines of GET /api/v1/orders/{id} |
NODE_ID | The id of your warehouse, step 1 |
SHIPMENT_ID and PARCEL_ID | The shipment's id and its parcel's id, step 3 |
The steps at a glance
| Step | Call | T-shirt line after it |
|---|---|---|
| Create the order | POST /api/v1/orders | Open, 2 ordered |
| Cancel one T-shirt | POST /api/v1/orders/{id}/lines/{lineId}/cancellations | Open, 1 remaining |
| Ship the other | POST /api/v1/orders/{id}/shipments | Shipped |
| The carrier delivers it | POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events | Delivered |
| The customer returns it | 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 in the example stays Open until a shipment includes it.
What you do
1. Register your warehouse once
Every shipment leaves a fulfillment node: a warehouse, a store or a third party logistics partner,
with the type warehouse, store or 3pl. Register each node once and keep its id.
curl -sS -X POST "https://api.orderex.se/api/v1/fulfillment/nodes" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Central warehouse", "type": "warehouse"}'
A node name is unique in your tenant: a second node with the same name gives 409 node-name-taken.
List your nodes with GET /api/v1/fulfillment/nodes.
2. Cancel one T-shirt
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-14T11:00:00+01:00", "quantity": 1}'
The line's quantities.cancelled becomes 1 and quantities.remaining 1, and the line stays
Open. 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.
3. Ship the other T-shirt
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/shipments" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "wms-58213",
"nodeId": "'"$NODE_ID"'",
"shippedAt": "2026-11-16T14:05:00+01:00",
"lines": [
{"orderLineId": "'"$TSHIRT_LINE_ID"'", "quantity": 1}
],
"parcels": [
{"trackingNumber": "00370712345678901234", "carrier": "Example Freight"}
]
}'
The response holds the shipment's id and the id of each parcel. The T-shirt line becomes
Shipped, since everything that is not cancelled has left the warehouse.
A shipment is checked as a whole, and nothing is stored when a check fails:
| Problem type | When |
|---|---|
shipment-node-unknown | nodeId is not one of your nodes. A deactivated node is accepted with the warning inactive_node |
shipment-line-not-on-order | A line is not a line of this order |
line-quantity-rule-violated | A line would ship more than ordered minus cancelled |
4. 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 becomes 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.
5. 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-20T16: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.
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, void 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 above |
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 money on the same order.