Game keys are highly sensitive. This page defines where plaintext appears, where it never appears, and how to handle deferred reveal.
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",
"deliveryMode": "key",
"integrationOrderContext": {
"schemaVersion": 1,
"salesCountryCode": "NL",
"currencyCode": "EUR",
"salesPriceGrossMinor": 7999,
"priceIncludesTax": true,
"salesTaxRatePercent": 21,
"salesChannel": "web",
"salesTaxAmountMinor": 1388,
"paymentProcessorReference": "pay_3QxK2mB9",
"checkoutSessionId": "cs_sandbox_10432"
}
}'Custody rules#
| Surface | Plaintext keys? |
|---|---|
| POST /api/seller/v1/orders (default keys mode) | Yes — persist immediately |
POST /api/seller/v1/keys/pull / POST /keys/export | Yes — persist immediately |
Webhooks (including order.fulfilled) | Never |
| GET /api/seller/v1/orders | Never — aggregates only |
| Browser, mobile app, CDN logs, support tickets | Never — server vault only |
Persist before buyer response#
On the first successful mutation response:
- Write each plaintext from
keys[]with its matching UUID fromkeyIds[]to your durable entitlement store. - Only then mark the storefront order fulfilled and respond to the buyer.
- Treat
order.fulfilledas a correlation signal — it will not re-send key codes.
If you lose the HTTP response without persisting keys, follow the Key recovery runbook: replay the same Idempotency-Key and body (returns the original response), then GET /orders?orderReference= and POST /orders/recover-keys, which re-reads the keys already sold under the reference without a new sale. POST /keys/export and POST /keys/pull are not recovery paths: they pull new keys. Webhook replay recovers metadata only.
Immediate fulfilment (default)#
{
"data": {
"type": "fulfilled",
"skuCode": "SANDBOX-ALWAYS-001",
"keys": ["AAAA-BBBB-CCCC-DDDD"],
"keyIds": ["8f21a9b0-1234-5678-9abc-def012345678"],
"pulled": 1,
"orderReference": "store-order-10432",
"activation": { "type": "worldwide", "countries": null }
}
}
activation is the SKU's guaranteed activation set (same object as GET /allocations), returned
with the keys on POST /orders, POST /keys/pull and POST /orders/{orderId}/fulfill so you can
show "activates in" without another call. It is the intersection across inventory batches, not
the batch this key came from — see Territory enforcement.
deferredReveal#
Deferred reveal happens when you send immediateFulfilment: false on POST /orders (or
POST /keys/pull). Inventory is assigned (pulled updated) but plaintext is omitted from the
HTTP body and data.deferredReveal is true:
{
"data": {
"type": "fulfilled",
"deferredReveal": true,
"keys": [],
"keyIds": ["8f21a9b0-1234-5678-9abc-def012345678"],
"pulled": 1,
"orderReference": "store-order-10432"
}
}
GET /orders never returns plaintext keys (aggregates only). Webhooks never carry plaintext
either. OpenAPI may include keyIds on order.fulfilled for correlation, but the durable rule
is:
Persist
keyIdsfrom the POST /orders response (authoritative for refunds / returns). Do not rely on webhooks or GET /orders as the source ofkeyIds.
Partner action:
- Treat the order as committed; store
keyIdseven whenkeys[]is empty. - When you need the keys, read them with POST /orders/recover-keys and the same
orderReference(scopeseller:orders:write, or the legacyseller:keys:pull; noIdempotency-Keyneeded). It reveals the keys already sold under that reference and never pulls new inventory. Every call is recorded as a reveal. - Do not assume
order.fulfilledincludes plaintextkeys[]. - Do not assume a second POST /orders with the same idempotency key will add keys — replay returns the stored response (still empty if that was the first outcome).
- Do not use
POST /keys/exportorPOST /keys/pullto get them: both sell you new keys.
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/recover-keys" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-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": []
}
}
A deferred order needs an orderReference: POST /orders always has one, but on
POST /keys/pull it is optional, and keys pulled without one cannot be read back this way. Keys
that were returned, refunded or revoked are not revealed; see the
Key recovery runbook for those answers.
Modes compared#
| Response | Keys in HTTP body | keyIds | Later delivery |
|---|---|---|---|
fulfilled (default) | keys[] populated | Persist from POST | Optional webhook for correlation |
fulfilled + deferredReveal | Empty keys[] | Persist from POST | POST /orders/recover-keys with the orderReference |
Pre-order placed with POST /orders (awaiting_release) | None | From the fulfill response | order.ready, then POST /orders/{orderId}/fulfill |
| Key-locked pre-order (bulk line) | None | From recover-keys | Automatic at release + order.preorder_fulfilled, then POST /orders/recover-keys |
Standalone pull and export#
Order commit (POST /orders) is the storefront golden path. Two sibling mutation routes pull from
an allocation without the full order aggregate:
| Method | Path | Purpose |
|---|---|---|
POST | /api/seller/v1/keys/pull | Pull keys as JSON (same contract checks as orders). Use Idempotency-Key. |
POST | /api/seller/v1/keys/export | Pull and return a ZIP archive (plaintext file inside) when keys are delivered immediately. Pre-order SKUs return JSON with reserved counts instead of a ZIP. Use Idempotency-Key. |
Both accept allocation / SKU + quantity bodies and optional integrationOrderContext, and both
pull new keys: each call is a sale. Scope: seller:keys:pull (or seller:orders:write) for
POST /keys/pull; POST /keys/export needs its own opt-in scope, seller:keys:export, which
neither of those grants. Prefer POST /orders for Profile B store checkout so you get aggregates,
webhooks, and finance lines in one flow. To re-read keys you already bought, use
POST /orders/recover-keys (Key recovery runbook).
The ZIP from POST /keys/export holds the keys but not their ids, and refunds and dispute freezes
take key ids. Send an orderReference with every export: GET /orders?orderReference= then lists
the key ids of that export, and POST /refunds also accepts orderReference with quantity.
Typed keys (contract date 2026-10-01)#
Pin X-Avrix-Api-Version: 2026-10-01 and every keys array in order responses and
POST /orders/recover-keys holds one object per key instead of a plaintext string (same order as
keyIds):
{
"id": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"type": "text",
"key": "ABCDE-FGHIJ-KLMNO",
"url": null,
"expiresAt": null,
"redemption": {
"platformCode": "steam",
"url": "https://store.steampowered.com/account/registerkey?key=ABCDE-FGHIJ-KLMNO",
"instructions": "Open Steam, go to Games > Activate a Product on Steam, and enter the code.",
"locale": "en"
}
}
type: "text"— the code is inkey.type: "link"— the buyer redeems aturl.type: "image"/"file"—urlis a signed download link valid for one hour (callrecover-keysagain for a fresh one);keycarries a code when the asset has one.redemptiontells the buyer where and how to activate, in the language ofAccept-Language(English when there is no translation).expiresAtis set when the Content Owner gave the key an expiry.
Earlier contract dates keep keys: string[]. Webhooks never carry typed keys.
Replacing a delivered key#
When a buyer reports that a key does not work, replace it instead of refunding:
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/ord_01J8XYZ/keys/7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f/replace" \
-H "Authorization: Bearer avrix_sk_your_key_here" \
-H "Idempotency-Key: replace-7c1e2d3f" \
-H "Content-Type: application/json" \
-d '{ "reason": "already_redeemed" }'
reason is already_redeemed, invalid, wrong_region or revoked. Avrix quarantines the old
key for the Content Owner and delivers a fresh key from the same allocation. It is not a new
sale: the order keeps its reference and settlement, and no allocation capacity is used.
- Within the Content Owner's policy (by default 1 replacement per order and 10 per store per
30 days) the answer is
200with the new key inkeysandkeyIds. Deliver it to the buyer. - Outside the policy the answer is
202withstatus: "pending"and areplacementId. The Content Owner decides in the console:- On approval you receive
key.replaced. ItskeyIdis the new key andreplacedKeyIdthe old one. Read the new key withPOST /orders/recover-keysand deliver the entry whosekeyIdmatches. - On refusal you receive
key.replacement_rejectedwith thereplacementId, the oldkeyIdand the Content Owner'sdecisionNote. The old key stays delivered and no new key is issued: refund the buyer and declare it withPOST /refunds, or file a return request.
- On approval you receive
- Asking again for the same key returns the same replacement.
GET /orders/{orderId}lists them underreplacements[]withstatus(pending,completedorrejected),replacedKeyIdand the newkeyId;recover-keysreturns the replacement keys, never the replaced ones. 409 KEY_NOT_REPLACEABLE: the key was returned, refunded or replaced already.409 NO_AVAILABLE_KEYS: the allocation has no key left; retry later with the sameIdempotency-Key.
In the sandbox, SANDBOX-REPLACE-PENDING-001 always answers 202 and is approved a moment later.
Revoked keys#
A Content Owner can revoke keys it already sold — a leaked batch, grey-market resale, a platform
revocation, fraud. You receive keys.revoked once per affected order with the key ids, the
reason and a recommendedAction:
replace— the allocation still has keys: callPOST /orders/{orderId}/keys/{keyId}/replacefor each revoked key (reasonrevoked) and send the buyer the new key.refund— no replacement stock: refund the buyer withPOST /refunds.
Revoked keys stop appearing in POST /orders/recover-keys (its revoked[] lists them instead,
also on a 404 when every key was revoked) and GET /orders/{orderId} lists them under
revocations[]. The order stays fulfilled. In the sandbox, keys sold on SANDBOX-REVOKE-001
are revoked right after delivery.
API key lifecycle (create/rotate/revoke) is separate — see API key management.