Hoppa till huvudinnehåll

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 headerYour own fact id
What it isA key you make up per requestexternalId, externalEventId or externalTransactionId in the body
WhereThe create and report calls listed belowEvery fact
How long7 daysFor as long as the fact exists
Same again, same bodyThe original 201 again, with Idempotent-Replayed: true200 OK with the fact as first reported
Same again, other body409 idempotency-key-reused409 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:

CallWhat it creates
POST /api/v1/ordersAn order
POST /api/v1/fulfillment/nodesA fulfillment node
POST /api/v1/orders/{id}/lines/{lineId}/cancellationsA cancellation
POST /api/v1/orders/{id}/lines/{lineId}/returnsA return
POST /api/v1/orders/{id}/shipmentsA shipment
POST /api/v1/orders/{id}/shipments/{shipmentId}/voidA void
POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-eventsA tracking event
POST /api/v1/orders/{id}/payment-factsA 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:

  1. 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.
  2. Send the request with Idempotency-Key. If you get no answer, send the same request with the same key.
  3. Within 7 days, the same key with the same body returns the original 201 Created, with the same body and Location, and the header Idempotent-Replayed: true. Nothing is created again.
  4. 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:

FactYour idUnique per
CancellationexternalIdLine
ReturnexternalIdLine
ShipmentexternalIdOrder
Tracking eventexternalEventId, optionalParcel. Without it, an event is unique by code and occurredAt
Payment facttype and externalTransactionIdOrder

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​

AnswerWhat you do
No answer, a timeout or a 5xxRetry the same request, with the same key and body
409 concurrency-conflictAnother fact on the same order was stored at the same moment. Retry the same request
200 on a factNothing: the fact was already stored
400 or 422Do not retry unchanged. Fix the request, see Errors
401Do 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 lateWhat OrderEx answers
A fact with an occurredAt in the pastAccepted. occurredAt may be any time before now, but at most 5 minutes after OrderEx's clock
A tracking event older than the parcel's latestAccepted with becameLatest: false, and it changes nothing else
A tracking event before the shipment's shippedAtAccepted
A return before its shipment422 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 cancelled422 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.