A reliable integration
Networks fail, and a call can time out after OrderEx has stored it. This guide shows how to send every call again without creating anything twice, what to retry, and how OrderEx treats facts that arrive late or out of order.
Two ways a call is made safe to repeat
Idempotency-Key header | Your own fact id | |
|---|---|---|
| What it is | A key you make up per request | externalId, externalEventId or externalTransactionId in the body |
| Where | The create and report calls listed below | Every fact |
| How long | 7 days | For as long as the fact exists |
| Same again, same body | The original 201 again, with Idempotent-Replayed: true | 200 OK with the fact as first reported |
| Same again, other body | 409 idempotency-key-reused | 409 fact-conflict, with the stored fact in existingFact |
A fact's own id already makes it safe to send again, so the header is optional for facts. Use the header where nothing in the body identifies the request, above all when you create an order without an external order number.
Idempotency-Key
These calls accept the header:
| Call | What it creates |
|---|---|
POST /api/v1/orders | An order |
POST /api/v1/fulfillment/nodes | A fulfillment node |
POST /api/v1/orders/{id}/lines/{lineId}/cancellations | A cancellation |
POST /api/v1/orders/{id}/lines/{lineId}/returns | A return |
POST /api/v1/orders/{id}/shipments | A shipment |
POST /api/v1/orders/{id}/shipments/{shipmentId}/void | A void |
POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events | A tracking event |
POST /api/v1/orders/{id}/payment-facts | A payment fact |
Adding a line (POST /api/v1/orders/{id}/lines) and registering a webhook (POST /api/v1/webhooks)
take no key and have no id of yours: sent again, each creates a second one. Before you retry one
of them, read the order or your webhooks to see whether the first call was stored.
How it works:
- Make a new key for each request you mean to make once, such as a UUID or your own id of the request, and keep it with the request until it has succeeded. A key is 1 to 100 visible ASCII characters.
- Send the request with
Idempotency-Key. If you get no answer, send the same request with the same key. - Within 7 days, the same key with the same body returns the original
201 Created, with the same body andLocation, and the headerIdempotent-Replayed: true. Nothing is created again. - The same key with another body gives 409
idempotency-key-reused. Use a new key for a new request.
Only a 201 is stored. A request that failed, such as a 400 or a 422, can be fixed and sent again
with the same key. Keys are scoped to your tenant.
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" \
-H "Idempotency-Key: return-rma-2291-1" \
-d '{"externalId": "rma-2291-1", "occurredAt": "2026-11-20T16:45:00+01:00", "quantity": 1}'
Your own fact ids
Every fact carries your id for it, and OrderEx stores a fact once per id:
| Fact | Your id | Unique per |
|---|---|---|
| Cancellation | externalId | Line |
| Return | externalId | Line |
| Shipment | externalId | Order |
| Tracking event | externalEventId, optional | Parcel. Without it, an event is unique by code and occurredAt |
| Payment fact | type and externalTransactionId | Order |
Use the id your own system already has, such as the warehouse's shipment number, so a fact sent twice
from two places is still one fact. A 409 fact-conflict means your system has two different facts
under one id: compare existingFact with what you sent, and fix the source.
What to retry
| Answer | What you do |
|---|---|
| No answer, a timeout or a 5xx | Retry the same request, with the same key and body |
409 concurrency-conflict | Another fact on the same order was stored at the same moment. Retry the same request |
| 200 on a fact | Nothing: the fact was already stored |
| 400 or 422 | Do not retry unchanged. Fix the request, see Errors |
| 401 | Do not retry. Check the key |
Wait longer between each retry, such as 1, 2, 4 and 8 seconds with some randomness, and stop after a limit you choose. Keep a request you gave up on, so you can send it later.
Facts that arrive out of order
Your systems will not always report facts in the order they happened. OrderEx accepts every fact in every order status. A line's quantities are sums of its facts, so the order in which they arrive does not change them, and a parcel's latest tracking event is the one that happened last.
| What arrives early or late | What OrderEx answers |
|---|---|
A fact with an occurredAt in the past | Accepted. occurredAt may be any time before now, but at most 5 minutes after OrderEx's clock |
| A tracking event older than the parcel's latest | Accepted with becameLatest: false, and it changes nothing else |
A tracking event before the shipment's shippedAt | Accepted |
| A return before its shipment | 422 line-quantity-rule-violated with returned-exceeds-shipped, and nothing is stored. Report the shipment, then send the return again |
| A shipment for a quantity that is cancelled | 422 line-quantity-rule-violated, and nothing is stored |
So when a report is rejected because a fact it depends on has not arrived yet, keep it and send it again after that fact. The same body and id are safe to send again.
Load the history you already have
When you connect a system that already has orders, report their history through the same calls,
oldest first: create each order, then its cancellations, shipments, tracking events, returns and
payment facts, each with the occurredAt from your system. Your own ids make the load safe to run
again from the start if it stops halfway. For a large history, ask OrderEx about loading it from a
file instead.
Next
Reading data shows how to read orders, their timeline and their shipments back.