Skip to content
ShirteeShirtee Developers
DEEN

Retrying orders safely

If POST /api/orders fails because of a timeout or network error, you cannot know whether the order was created. Without further measures a retry would create a second order. The Idempotency-Key header prevents that.

How it works

Section titled “How it works”

Send a key with the order request:

Terminal window
curl -X POST https://gateway.shirtee.cloud/api/orders \
  -H "Authorization: Bearer $SHIRTEE_API_KEY" \
  -H "Idempotency-Key: 6b0e4c1e-8a57-4f7b-9d6a-2f6e0f8a1c11" \
  -H "Content-Type: application/json" \
  -d @order.json
Retry with … Result
the same key and the same body You get the first order back (201); no second one is created.
the same key and a different body 422 with extra.error = IDEMPOTENCY_KEY_REUSED. Nothing is created.
no key Every call creates a new order.

Rules for the key

Section titled “Rules for the key”
  • 1 to 128 visible ASCII characters. A UUID works well.
  • It applies to your account only. Two merchants can use the same value without interfering.
  • It stays bound to the created order. The code defines no expiry time.
  • Concurrent requests with the same key create the order only once.
Section titled “Recommended flow”
  1. Generate a key once per order and store it with your order before you send.
  2. On timeout, network error or 5xx, retry with the same key and the same body.
  3. Generate a new key only when you deliberately want a new order.