Idempotency & retries

Idempotency-Key contract, orderReference, and safe retry behavior.

Retry safety and order identity are different problems. Use Idempotency-Key so a network retry cannot double-fulfil the same HTTP mutation. Use orderReference so finance, support, and recovery can find your store order. Prefer both on every commercial write — changing either after the buyer pays breaks recovery.

Retry decision tree#

Diagram

Example#

curl -s -X POST "https://api.avrix.io/api/seller/v1/orders" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Idempotency-Key: store-order-10432" \
  -H "Content-Type: application/json" \
  -d '{
  "skuCode": "SANDBOX-ALWAYS-001",
  "quantity": 1,
  "orderReference": "store-order-10432",
  "expectedUnitPriceCents": 5999,
  "countryCode": "NL",
  "integrationOrderContext": {
    "schemaVersion": 1,
    "salesCountryCode": "NL",
    "currencyCode": "EUR",
    "salesPriceGrossMinor": 7999,
    "priceIncludesTax": true,
    "salesTaxRatePercent": 21,
    "salesChannel": "web",
    "salesTaxAmountMinor": 1388,
    "paymentProcessorReference": "pay_3QxK2mB9",
    "checkoutSessionId": "cs_sandbox_10432"
  }
}'

This page is the full contract for Idempotency-Key behaviour.

Who needs this#

Checkout and platform engineers implementing POST /orders (and other commercial writes) with safe retries.

TL;DR#

  • Same Idempotency-Key + identical body → replay the cached successful response (no second side effect) for 24 hours.
  • Failed responses are never cached. After any 4xx/5xx, fix the cause and retry the same key — the request re-executes against live state.
  • Same key + different body → 409 IDEMPOTENCY_KEY_MISMATCH.
  • Never mint a new key to “force” a timed-out order — that risks a second fulfilment against the same charge.
  • Keep a stable orderReference as a secondary re-reveal safety net when quantity matches.

Two correlation layers#

MechanismRole
Idempotency-KeyAt-most-once HTTP retry semantics for identical canonical JSON (24-hour window)
orderReferenceBusiness identity visible in aggregates, finance, and support (“find store-order-10432”), plus a secondary pull-safety net (below)

They solve different problems. Prefer both on order flows.

ScenarioIdempotency-KeyorderReference
Normal checkoutStable per payment attempt (e.g. checkout session id)Same store order id
Retry after timeoutSame keySame reference
Second charge on a new paymentNew keyNew reference (or agreed suffix policy)

Header rules#

RuleDetail
Format1–64 characters: [a-zA-Z0-9_-]
RequiredOn the routes listed below. Missing or malformed → 400 IDEMPOTENCY_KEY_REQUIRED on contract date 2026-12-01 and later, 400 BAD_REQUEST on earlier dates
WindowHonoured for 24 hours (cached successful response TTL)
Body matchCanonical JSON hash (key order and insignificant whitespace do not matter)
Path matchOn contract date 2026-12-01 and later, the path parameters count too: the same key on PATCH /allocations/{id} or POST /orders/{orderId}/keys/{keyId}/replace with another id is 409 IDEMPOTENCY_KEY_MISMATCH. Earlier dates compare the body only and replay the first answer. Retry with the same X-Avrix-Api-Version you first sent
Replay headerSuccessful replays always include Idempotency-Replayed: true
ScopeNamespaced by endpoint + company + API key id — rotating or switching keys voids replay against the old key’s cache
Strict bulk cartsA refused strict: true cart stores nothing (no line and no cart record), so a retry with the same key runs the whole cart again; a fulfilled strict cart replays as one response
At restThe cached response never holds plaintext keys, the keys/export ZIP, a webhook signing secret or an API key secret. A replay re-reads the same keys from their keyIds (the audited read-only path POST /orders/recover-keys uses) and rebuilds the ZIP; if they cannot be re-read it answers 503 KEY_DECRYPT_FAILED — retry the same key. A replayed POST /webhooks, POST /keys or POST /keys/{id}/rotate omits the secret and carries secretRedacted: true (the secret is shown once; rotate it if lost)

Claim lifecycle (in-flight)#

While a request holds the key, a concurrent retry with the same Idempotency-Key receives 409 IDEMPOTENCY_REQUEST_IN_FLIGHT and should honour Retry-After.

TimingValueMeaning
Claim hold120 secondsMaximum time an in-flight claim is considered live before another worker may take it over as stale
Suggested Retry-After5 secondsReturned on in-flight conflicts (and on some store-unavailable responses)

Do not mint a new key while waiting — retry the same key and body after Retry-After.

Error-response replay vs release#

No error is ever cached. Only successful (2xx) responses are stored for replay. On POST /orders (and the same claim/commit pattern elsewhere):

OutcomeIdempotency behaviour
Success (2xx)Committed and replayed for the TTL
Any failure (4xx/5xx) — state-dependent gates (KYB_NOT_VERIFIED, TREASURY_CAPABILITY_MISSING, INSUFFICIENT_WALLET_BALANCE, 409 NO_AVAILABLE_KEYS), validation errors, transient 5xxClaim is released — a retry with the same key re-executes against live state, so fixing the underlying cause (complete KYB, top up the wallet, restock) makes the same request succeed without rotating the key
Unhandled throw before commitClaim is released in a safety net so the partner can retry

Every failure path either has no side effects or compensates them (key quarantine, hold release), so re-execution is always safe. Failures observed on one attempt are re-evaluated — an error you received earlier is not proof of the current account state.

If the idempotency store cannot persist a final response after side effects ran, the API may return 503 IDEMPOTENCY_STORE_UNAVAILABLE — still retry with the same key.

Legacy rows without a body hash#

Cached rows that lack a stored request-body hash are treated as fail-closed: 409 IDEMPOTENCY_KEY_MISMATCH. They are not replayed, even if the body looks identical. Only freshly written hashed entries are replayable.

Routes that require Idempotency-Key#

Generated from the API reference: the reference, the generated clients and this page give the same answer. A route that requires the header refuses a request without it (see Header rules).

MethodPath
POST/api/seller/v1/access/proposals/{id}/accept
POST/api/seller/v1/access/proposals/{id}/decline
POST/api/seller/v1/chargebacks/resolve
POST/api/seller/v1/disputes/{freezeId}/release
POST/api/seller/v1/disputes/freeze
POST/api/seller/v1/keys/export
POST/api/seller/v1/keys/pull
POST/api/seller/v1/keys/return
POST/api/seller/v1/orders
POST/api/seller/v1/orders/{orderId}/extend
POST/api/seller/v1/orders/{orderId}/fulfill
POST/api/seller/v1/orders/{orderId}/keys/{keyId}/replace
POST/api/seller/v1/orders/bulk
POST/api/seller/v1/orders/cancel
POST/api/seller/v1/orders/commit
POST/api/seller/v1/orders/fulfillments/{fulfillmentId}/regenerate
POST/api/seller/v1/orders/fulfillments/{fulfillmentId}/revoke
DELETE/api/seller/v1/orders/hold
POST/api/seller/v1/orders/hold
DELETE/api/seller/v1/orders/hold/{holdId}
POST/api/seller/v1/orders/reservations/{reservationId}/commit
POST/api/seller/v1/orders/reservations/{reservationId}/extend
POST/api/seller/v1/orders/reserve
POST/api/seller/v1/refunds
POST/api/seller/v1/returns
POST/api/seller/v1/returns/{returnRequestId}/cancel
POST/api/seller/v1/returns/{returnRequestId}/evidence
POST/api/seller/v1/returns/{returnRequestId}/reply
POST/api/seller/v1/webhooks

Routes that accept Idempotency-Key but do not require it. Send one on every call you might retry: the same key and body replay the first answer with Idempotency-Replayed: true and nothing runs twice. Without a key a retry runs again, as it always has. Accepting the header is additive, so these routes require it on no contract date.

MethodPathRequired
PATCH/api/seller/v1/allocations/{id}No, on every contract date
POST/api/seller/v1/allocations/requestsNo, on every contract date
POST/api/seller/v1/allocations/requests/{id}/cancelNo, on every contract date
POST/api/seller/v1/api-keysNo, on every contract date
POST/api/seller/v1/api-keys/{id}/rotateNo, on every contract date
POST/api/seller/v1/keysNo, on every contract date
POST/api/seller/v1/keys/{id}/rotateNo, on every contract date
POST/api/seller/v1/promotions/deals/{responseId}/respondNo, on every contract date
POST/api/seller/v1/promotions/shares/{shareId}/acceptNo, on every contract date
POST/api/seller/v1/promotions/shares/{shareId}/declineNo, on every contract date
POST/api/seller/v1/sandbox/allocations/{allocationId}/stock-eventsNo, on every contract date
POST/api/seller/v1/sandbox/allocations/requests/{requestId}/resolveNo, on every contract date
POST/api/seller/v1/sandbox/promotions/deals/{responseId}/windowNo, on every contract date
POST/api/seller/v1/sandbox/resetNo, on every contract date
PATCH/api/seller/v1/webhooks/{id}No, on every contract date
POST/api/seller/v1/webhooks/{id}/deliveries/replayNo, on every contract date

What a retry with the same key returns on these routes:

RouteReplayed answer
POST /allocations/requestsThe first answer; no second request is filed and the grant grows once
POST /promotions/shares/{shareId}/accept, .../decline, POST /promotions/deals/{responseId}/respondThe first answer. On contract date 2026-12-01 and later a repeat without a key is safe too: the same answer returns 200, a different answer 409 CONFLICT
PATCH /webhooks/{id} with rotateSecret: trueThe secret the first call minted, without rotating again; secretRedacted: true once the endpoint has been rotated again since
POST /webhooks/{id}/deliveries/replayThe first answer; no delivery is cloned twice
POST /keysThe first answer without key (never stored), with secretRedacted: true; no second key is created
POST /keys/{id}/rotateThe first answer without secret (never stored), with secretRedacted: true; the key is not rotated again. Rotate with overlapSeconds so a lost answer never locks you out (Rotating a key)
PATCH /allocations/{id}The first answer

Outcomes#

SituationResult
Same key, identical body, cached final responseCached response replayed — Idempotency-Replayed: true — no second side effect
Same key, different body (or legacy row without hash)409 IDEMPOTENCY_KEY_MISMATCH with details.requestBodyHash
Same key and body, another path parameter (contract date 2026-12-01 and later)409 IDEMPOTENCY_KEY_MISMATCH; earlier dates replay the first answer
Same key, original still processing409 IDEMPOTENCY_REQUEST_IN_FLIGHT — honour Retry-After (typically 5s)
Idempotency store unavailable503 IDEMPOTENCY_STORE_UNAVAILABLE — fail closed; retry with the same key
Same key after a released validation errorNew attempt proceeds (not a replay)

Example mismatch#

JSON
{
  "code": "IDEMPOTENCY_KEY_MISMATCH",
  "message": "Idempotency-Key was already used with a different request body",
  "details": {
    "requestBodyHash": "a3f1c9..."
  },
  "requestId": "req_01J8XYZ...",
  "doc_url": "https://docs.avrix.io/seller-api/idempotency"
}

Compare your outbound body’s canonical hash to details.requestBodyHash, or use a new key only when the mutation intent is genuinely new.

orderReference as secondary recovery#

orderReference is your store’s stable order id. On key pulls / POST /orders, when the same allocation already has live pulled keys (revealed / assigned / redeemed) for that reference:

  • If at least quantity live keys were already pulled for (allocation, orderReference), Avrix re-reveals those keys’ plaintext (no additional inventory consumption). Scope is per allocation — the same reference on a different allocation is a different pull.
  • If fewer than quantity live keys exist for that pair (partial prior fulfilment), the request is rejected with 409 ORDER_REFERENCE_CONFLICT. There is no top-up: a larger quantity never pulls additional keys under an existing reference. Use a new orderReference for a new sale.
  • If the order under that reference was refunded or returned, the reference is spent: a new POST /orders with it answers 409 ORDER_REFERENCE_CONFLICT, whatever the quantity. A refunded sale is never sold a second time under the same reference.
  • If the order never completed (Avrix compensated a failed delivery and no key reached the buyer), retry with the same orderReference and Idempotency-Key.

ORDER_REFERENCE_CONFLICT example#

JSON
{
  "code": "ORDER_REFERENCE_CONFLICT",
  "message": "orderReference already fulfilled 1 key(s); requested 3. Use a new orderReference for a new sale.",
  "recoverable": false,
  "hint": "Use a new orderReference for a new sale. An orderReference replays its original keys only for the same quantity; a larger or smaller quantity is refused.",
  "details": {
    "recommendedAction": "fix_request_body_or_new_key",
    "pullError": "ORDER_REFERENCE_CONFLICT"
  },
  "requestId": "req_01J8XYZ...",
  "doc_url": "https://docs.avrix.io/seller-api/errors#order-reference-conflict"
}

Recovery preference

  1. Primary: retry with the same Idempotency-Key and identical body (HTTP idempotency).
  2. Secondary: keep a stable orderReference so a crash that lost the HTTP response (or used a new key by mistake) can still re-reveal already-pulled keys when quantity matches the original fulfilment.

Never invent a new orderReference for the same paid checkout. Never change quantity on a recovery retry — replay requires the requested quantity to equal the live keys already fulfilled; a larger or a smaller quantity returns 409 ORDER_REFERENCE_CONFLICT. A replay returns the original keys and sends no second order.fulfilled webhook.

Safe retry pattern#

  1. Generate the key once when the buyer commits payment (not per HTTP attempt).
  2. Persist key + body + orderReference in your database before the first call.
  3. On timeout / 5xx / connection drop: retry with the same key and same body.
  4. On IDEMPOTENCY_REQUEST_IN_FLIGHT: wait for Retry-After, then retry same key/body.
  5. On IDEMPOTENCY_STORE_UNAVAILABLE or HOT_PATH_TIMEOUT: backoff and retry same key/body — never invent a new key. Either can arrive after the order was fulfilled and billed; refund only when GET /orders?orderReference= shows no live keys (error playbook).
  6. On IDEMPOTENCY_KEY_MISMATCH: stop — fix the client; do not “force through” with a new key against the same payment.
  7. On 409 NO_AVAILABLE_KEYS (vendor stock is empty) or ALLOCATION_EXCEEDED (your allocation cap is reached; request more with POST /allocations/requests): nothing was delivered, so refund at your PSP — Avrix will not auto-refund. Failures are not cached, so a later retry with the same key is re-evaluated — it succeeds only if stock has actually been replenished.

Key rotation voids replay#

The replay namespace includes the API key id (see Header rules above). A retry sent with a different key — for example after a rotation — cannot see the cache written by the old key, so it executes as a brand-new request instead of replaying the cached response. An in-place rotation (POST /keys/{id}/rotate) keeps the key id, so retries sent with the new secret still replay.

Rotation-safe retry recipe:

  1. Stop issuing new mutations with the old key, but keep the old key valid.
  2. Drain in-flight retries: wait out your full retry/backoff window (plus any queued retry jobs) so every retry of an old-key mutation still runs on the old key.
  3. Only then revoke the old key. See Rotating a key.
  4. Never re-send an old-key mutation with the new key “to be safe”. On POST /orders the orderReference backstop protects against a double sale, but other mutations would execute a second time.

Choosing a key#

Good: checkout session id, PSP payment intent id, or a UUID minted once per logical mutation.

Bad: timestamps, random values per attempt, buyer email, or reusing one key across unrelated purchases.

Common mistakes#

  • New Idempotency-Key on every HTTP retry of the same payment.
  • Reusing one key across unrelated purchases.
  • Treating orderReference as a substitute for HTTP idempotency on the first attempt.
  • Ignoring Idempotency-Replayed: true and double-applying side effects in your OMS.

Next steps#

What links here

Published guides that link to this page.

Search docs

Search documentation…