Your buyer paid, your POST /orders call happened — and the response with the key plaintext is gone: a crash mid-request, a dropped connection, a deploy at the wrong second. This page is the complete, ordered recovery procedure. Work it top to bottom; each step is strictly safer than inventing a new order.
Where key plaintext can be read#
Key plaintext is returned by the response of the call that sold the keys (POST /orders, and the other order and pull writes), by an idempotent replay of that call, and by POST /orders/recover-keys, which re-reads keys you already bought. It is never available via:
- webhooks — payloads are redacted by design (
order.fulfilledcarries key ids, not codes); - GET /orders — lookup and listing responses carry key ids only;
- delivery replay — replays are clones of redacted payloads.
Step 1 — Replay with the same Idempotency-Key#
Retry POST /orders with the same Idempotency-Key and the identical JSON body. Within
the 24-hour replay window the original response — including key plaintext — is returned with
Idempotency-Replayed: true and no second side effect. If the original request never
executed, it executes now. Either way you end with exactly one order.
Step 2 — Look the order up#
If the replay window has passed, the key was lost, or retries keep failing, ask whether the order exists:
curl -s "https://api.avrix.io/api/seller/v1/orders?orderReference=store-order-10432" \
-H "Authorization: Bearer avrix_sk_your_key_here"
The lookup never returns plaintext. It tells you which step comes next: the order was fulfilled
(step 3) or it does not exist (step 4). An order that is still waiting (awaiting_stock,
awaiting_release, ready) has delivered no keys yet: follow
Order lifecycle instead.
Step 3 — Re-read the keys with POST /orders/recover-keys#
When the order was fulfilled and you do not hold its keys:
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/recover-keys" \
-H "Authorization: Bearer avrix_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "orderReference": "store-order-10432" }'
{
"data": {
"orderReference": "store-order-10432",
"recovered": 1,
"keyIds": ["8f21a9b0-1234-5678-9abc-def012345678"],
"keys": ["AAAAA-BBBBB-CCCCC"],
"skuIds": ["3f9a1c22-7b6d-4e51-9f0a-2c8e4d6b1a35"],
"revoked": [],
"frozen": []
}
}
- It returns the keys that are still live under that
orderReference. It never pulls new inventory and is never a new sale; every call is recorded as a key reveal. - Scope:
seller:keys:pull(orseller:orders:write). NoIdempotency-Keyis needed; the call is safe to repeat. - Returned and refunded keys are not included. Keys the Content Owner revoked are listed under
revoked[]and keys frozen by an open dispute underfrozen[], in both cases without plaintext. 404 NOT_FOUNDmeans nothing can be read under the reference: the order never fulfilled, every key was returned or refunded, every key was revoked (details.revoked), or every live key is frozen (details.frozen).- On contract date
2026-10-01and later,keysholds typed key objects instead of strings (Fulfilment keys).
A POST /orders sent again with the same orderReference, the same SKU and the same
quantity also answers with the original keys and consumes no inventory, so a retry that lost its
idempotency record does not sell twice. A different quantity answers 409
ORDER_REFERENCE_CONFLICT. Prefer recover-keys for recovery: it needs no price binding and
works after a partial refund.
Step 4 — The order does not exist#
If the lookup shows no order under the reference, the original request never committed. Send the
same request again — same Idempotency-Key, same body, same orderReference — and it places the
order; or refund the buyer at your payment processor. Refund only when the lookup shows no live
keys for the reference. Do not change the orderReference: it is what stops a second sale if the
first request turns out to have committed after all.
Step 5 — Support escalation#
When the steps above cannot recover (for example, recover-keys keeps answering 5xx), contact
support@avrix.io with:
- the
X-Request-Idof the failed call (orrequestIdfrom the error body), - the
Idempotency-KeyandorderReferenceyou used, - the approximate timestamp with timezone.
Avrix can trace exactly what the request did — including whether keys were issued — from the request id alone.
What is not a recovery path#
POST /keys/export and POST /keys/pull pull new keys from an allocation: each call is a
new sale that is billed. POST /keys/export returns them as a ZIP file and needs the opt-in
seller:keys:export scope. Neither re-reads keys you already bought; use recover-keys for that,
one orderReference at a time.
Deferred reveal#
If you deliberately ordered with immediateFulfilment: false (deferred reveal), the plaintext was
never in the response. recover-keys is also how you read those keys, with the same
orderReference and the same answers as above; see
Fulfilment and keys.
Related#
- Idempotency — the full retry contract
- Order lifecycle — states and events
- Fulfilment keys — custody model
- Integration recipes — the
recover-keysrecipe - Troubleshooting