Guides

Idempotency

Networks fail. An Idempotency-Key lets you retry a POST request without accidentally creating a second order, refund or stock adjustment.

On this page

How it works
Example
Conflicts

How it works

Send a unique Idempotency-Key header (a UUID v4 is ideal) with any POST request.
The first response for that key is stored for 24 hours, per store.
Repeating the request with the same key and the same body returns the stored response — status code and body — without doing the work again.
GET, PATCH and DELETE are already safe to repeat and don’t need a key.

Example

Generate the key once per logical operation, and reuse it for every retry of that operation:

Shell

curl -X POST https://api.sellorchard.com/v1/orders/2051/refunds \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
  -d '{"amount": "19.99", "note": "Damaged in transit"}'

Don’t generate a new key inside your retry loop — that defeats the purpose. Tie the key to the thing you’re doing (for example, your own refund record ID).

Conflicts

Reusing a key with a different body returns 409:

409 Conflict

{
  "error": {
    "type": "conflict",
    "message": "This Idempotency-Key was already used with a different request body."
  }
}