Idempotency

A write can time out after the store has applied it. The Idempotency-Key header makes repeating it safe: the store applies the request once and responds to the repeat with the saved result.

Loading the search index…

Idempotency

How to use it

  1. Make a new key for each operation, such as a UUID, and store it with the operation in your system.
  2. Send it in the Idempotency-Key header of the write.
  3. After a timeout or a network error, repeat the request with the same key and the same body.

The response is kept for 24 hours. A repeat gets it back — the same status and body — with Idempotent-Replayed: true:

Request
curl -X POST "https://api.saleya.app/v1/inventory-levels/set" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 0b4a9a3c-6c4e-4f0e-9a43-2f8f6d1b7e21' \
  -H "Content-Type: application/json" \
  -d '{
  "variant_id": 1042,
  "location_id": 3,
  "on_hand": "24",
  "expected_on_hand": "20"
}'
Response
HTTP/1.1 200 OK
Idempotent-Replayed: true

{
  "status": "applied",
  "inventory_level": {
    "variant_id": 1042,
    "location_id": 3,
    "on_hand": "24",
    "reserved": "2",
    "available": "22",
    "updated_at": "2026-11-11T14:30:00Z"
  }
}

Every write takes the key: POST, PATCH, PUT and DELETE. A key is 1 to 255 visible ASCII characters.

Rules

CaseResponse
The same key with another method, path or body422 idempotency_key_reused
The first request with the key is still running409 idempotency_key_in_use with Retry-After: 1
The first request was rejectedAn error is not kept, so the repeat runs again
More than 24 hours have passedThe key is forgotten, and the repeat runs as a new request
The header cannot be read422 invalid_idempotency_key

Bodies are compared by content: the order of keys in JSON does not matter. Keys of one app never collide with keys of another.

All or nothing

Each write runs as one transaction: it is applied whole or not at all, and an error leaves nothing behind. Some endpoints check more on their own: stock is set against the quantity you counted, expected_on_hand, and stock that moved since gets 409 stock_on_hand_changed.

Next guideVersions and If-Match