Retries and duplicate protection
Why sending the same order twice never creates two orders, which errors to retry, and how to retry safely.
Duplicate protection with external_order_id
Every order you send carries your own order number in external_order_id. For each API access, one external_order_id leads to at most one order in the shop. This holds even if two requests with the same number arrive at the same time.
| Request | Response |
|---|---|
First request with APP-100234 |
201 Created, the new order |
Any later request with APP-100234 |
200 OK, the existing order, "duplicate": true |
Later request with APP-100234, but the order was deleted in the shop |
409 order_deleted |
A repeated request creates nothing. The response shows the order as it is now:
{
"data": {
"id": 48211,
"order_number": "48211",
"external_order_id": "APP-100234",
"duplicate": true,
"customer_id": 9021,
"customer_created": false,
"status_id": 1,
"status": "Incoming order",
"payment_method_id": 3,
"referrer_id": 17,
"shipping_method_id": 4,
"shipping_method": "Parcel",
"shipping_cost_gross": 4.9,
"shipping_cost_source": "app",
"items": [
{ "sku": "SKU-1001", "quantity": 2, "unit_price_gross": 29.9, "price_source": "app" }
],
"grand_total_gross": 64.7,
"currency": "EUR"
},
"warnings": []
}
On a repeat, customer_created is always false and warnings is always empty, even if the first request created a customer or returned warnings.
Points to keep in mind:
external_order_idis compared exactly, including upper and lower case. Leading and trailing spaces are removed.- The protection applies per access. The same number sent with a key of a different access creates a separate order. Renewing a key does not change the access.
- A repeat returns the existing order unchanged. If you change the data and send it again with the same number, the changes are ignored. To correct an order, contact the operator.
- The request is checked before the duplicate lookup. A repeat with invalid data answers
422, and a repeat while the access is misconfigured answers422 client_not_configured, even if the order exists.
When to retry
| Situation | Retry? |
|---|---|
| Connection lost, timeout, no response | Yes, with unchanged data |
429 rate_limited |
Yes, after Retry-After seconds |
500, 502, 503, 504 |
Yes, with unchanged data and increasing wait time |
200 with duplicate: true |
No, the order exists. Store its id. |
422 |
No. Fix the data first. |
409 order_deleted |
No. Inform the operator. |
401, 403, 404, 405 |
No. Fix the key, scope or request. |
If you do not know whether a request reached the shop, for example after a timeout, send it again with the same external_order_id and the same data. Either the order is created now (201), or you receive the one created by the first attempt (200, duplicate: true).
Backoff
Double the wait time after each failed attempt, for example 2, 4, 8, 16 seconds, and stop after a fixed number of attempts. If the response contains Retry-After, wait at least that long. Keep failed orders in a queue in your app so they are not lost while the shop is unreachable.
attempt 1 -> timeout
wait 2 s
attempt 2 -> 503
wait 4 s
attempt 3 -> 201 Created
Other write requests
Duplicate protection by number exists for orders only. For customer endpoints:
- Creating an address that already exists for the customer creates no second one. The API answers
200with the existing address instead of201. - Setting labels and setting the customer class lead to the same result when repeated.
- Creating a note creates a new note on every successful request. If you retry after a lost response, the note may exist twice.