Fulfillment & keys

Key custody, deferred reveal, and why GET /orders never returns plaintext.

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#

SurfacePlaintext keys?
POST /api/seller/v1/orders (default keys mode)Yes — persist immediately
POST /api/seller/v1/keys/pull / POST /keys/exportYes — persist immediately
Webhooks (including order.fulfilled)Never
GET /api/seller/v1/ordersNever — aggregates only
Browser, mobile app, CDN logs, support ticketsNever — server vault only

Persist before buyer response#

On the first successful mutation response:

  1. Write each plaintext from keys[] with its matching UUID from keyIds[] to your durable entitlement store.
  2. Only then mark the storefront order fulfilled and respond to the buyer.
  3. Treat order.fulfilled as 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)#

JSON
{
  "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:

JSON
{
  "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 keyIds from the POST /orders response (authoritative for refunds / returns). Do not rely on webhooks or GET /orders as the source of keyIds.

Partner action:

  1. Treat the order as committed; store keyIds even when keys[] is empty.
  2. When you need the keys, read them with POST /orders/recover-keys and the same orderReference (scope seller:orders:write, or the legacy seller:keys:pull; no Idempotency-Key needed). It reveals the keys already sold under that reference and never pulls new inventory. Every call is recorded as a reveal.
  3. Do not assume order.fulfilled includes plaintext keys[].
  4. 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).
  5. Do not use POST /keys/export or POST /keys/pull to get them: both sell you new keys.
Bash
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" }'
JSON
{
  "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#

ResponseKeys in HTTP bodykeyIdsLater delivery
fulfilled (default)keys[] populatedPersist from POSTOptional webhook for correlation
fulfilled + deferredRevealEmpty keys[]Persist from POSTPOST /orders/recover-keys with the orderReference
Pre-order placed with POST /orders (awaiting_release)NoneFrom the fulfill responseorder.ready, then POST /orders/{orderId}/fulfill
Key-locked pre-order (bulk line)NoneFrom recover-keysAutomatic 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:

MethodPathPurpose
POST/api/seller/v1/keys/pullPull keys as JSON (same contract checks as orders). Use Idempotency-Key.
POST/api/seller/v1/keys/exportPull 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):

JSON
{
  "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 in key.
  • type: "link" — the buyer redeems at url.
  • type: "image" / "file" — url is a signed download link valid for one hour (call recover-keys again for a fresh one); key carries a code when the asset has one.
  • redemption tells the buyer where and how to activate, in the language of Accept-Language (English when there is no translation). expiresAt is 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:

Bash
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 200 with the new key in keys and keyIds. Deliver it to the buyer.
  • Outside the policy the answer is 202 with status: "pending" and a replacementId. The Content Owner decides in the console:
    • On approval you receive key.replaced. Its keyId is the new key and replacedKeyId the old one. Read the new key with POST /orders/recover-keys and deliver the entry whose keyId matches.
    • On refusal you receive key.replacement_rejected with the replacementId, the old keyId and the Content Owner's decisionNote. The old key stays delivered and no new key is issued: refund the buyer and declare it with POST /refunds, or file a return request.
  • Asking again for the same key returns the same replacement. GET /orders/{orderId} lists them under replacements[] with status (pending, completed or rejected), replacedKeyId and the new keyId; recover-keys returns 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 same Idempotency-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: call POST /orders/{orderId}/keys/{keyId}/replace for each revoked key (reason revoked) and send the buyer the new key.
  • refund — no replacement stock: refund the buyer with POST /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.

What links here

Published guides that link to this page.

Search docs

Search documentation…