Hoppa till huvudinnehåll

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:

VariableWhere you get it
ORDEREX_API_KEYYour API key, step 1
ORDER_ID and TSHIRT_LINE_IDThe order's id and the T-shirt line's id, step 4
SHIPMENT_ID and PARCEL_IDThe shipment's id and its parcel's id, step 5

The steps at a glance​

StepCallT-shirt line after it
Where Getting started leaves itPOST /api/v1/orders/{id}/shipmentsPartiallyShipped, 1 of 2 shipped
Cancel the second T-shirtPOST /api/v1/orders/{id}/lines/{lineId}/cancellationsShipped, nothing remaining
The carrier delivers the parcelPOST /api/v1/orders/{id}/parcels/{parcelId}/tracking-eventsDelivered
The customer returns the T-shirtPOST /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 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:

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.

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 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, wms-58213 can 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​

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
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 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.