Skip to main content

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.

VariableWhere you get it
ORDEREX_API_KEYYour API key
ORDER_IDorderId when you create the order
TSHIRT_LINE_IDThe id of the T-shirt line in lines of GET /api/v1/orders/{id}
NODE_IDThe id of your warehouse, step 1
SHIPMENT_ID and PARCEL_IDThe shipment's id and its parcel's id, step 3

The steps at a glance​

StepCallT-shirt line after it
Create the orderPOST /api/v1/ordersOpen, 2 ordered
Cancel one T-shirtPOST /api/v1/orders/{id}/lines/{lineId}/cancellationsOpen, 1 remaining
Ship the otherPOST /api/v1/orders/{id}/shipmentsShipped
The carrier delivers itPOST /api/v1/orders/{id}/parcels/{parcelId}/tracking-eventsDelivered
The customer returns itPOST /api/v1/orders/{id}/lines/{lineId}/returnsReturned
Void a shipment reported by mistakePOST /api/v1/orders/{id}/shipments/{shipmentId}/voidBack to what it was before the shipment

OrderEx derives lineStatus from the line's quantities after every fact, in this order:

  1. Cancelled when all of the ordered quantity is cancelled.
  2. Returned when everything shipped has been returned, and PartiallyReturned when some of it has.
  3. Delivered when all of the quantity that is not cancelled is delivered.
  4. Shipped when all of it is shipped, and PartiallyShipped when some of it is.
  5. Open otherwise.

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 typeWhen
shipment-node-unknownnodeId is not one of your nodes. A deactivated node is accepted with the warning inactive_node
shipment-line-not-on-orderA line is not a line of this order
line-quantity-rule-violatedA 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:

CodeMeaning
InfoReceivedThe carrier has the shipment's details
InTransitThe parcel is on its way
OutForDeliveryThe parcel is out for delivery
DeliveredThe parcel is delivered
DeliveryFailedA delivery attempt failed
ReturnedToSenderThe parcel is on its way back
ExceptionSomething 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 Voided and 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 lineStatus follows.
  • 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​

EndpointStateUse instead
PATCH /api/v1/orders/{id}/lines/{lineId}/quantitiesDeprecated. Still replaces ordered and invoiced; any other changed quantity gives 422 quantity-reported-as-factThe cancellation, shipment, tracking and return calls above
PATCH /api/v1/orders/{id}/deliveryClosed, answers 422 endpoint-closedPOST /api/v1/orders/{id}/shipments and tracking events
PATCH /api/v1/orders/{id}/lines/{lineId}/statusClosed, answers 422 endpoint-closedNothing: 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.