Store integration profiles

Profile A/B/C checkout patterns — preview, hold, and hot-drop.

Choose one profile for your game store. Each profile is a call sequence and scope set — not a different API product. All profiles use the same Seller API at https://api.avrix.io.

Start here if you are new: 30-minute quickstart and SDK & helpers.

Profile A vs Profile B (pick one)#

Profile A — MinimalProfile B — Production
GoalProve checkout end-to-end quicklyRun a live storefront safely
CatalogBrowse GET /products + check allocationsFull sellable sync (syncSellableCatalog + deltas)
CheckoutPreview → PSP → POST /ordersSame, plus availability checks and optional soft hold
OpsManual / lightWebhooks, reconcile by orderReference, low-stock signals
When to useFirst integration, sandbox certificationLive traffic, multi-SKU catalog, support desk

Profile B is the golden path for a live storefront; the quickstart and the SDKs follow it. Profile C adds hot-drop reserve/commit on top of B for launch-day contention. You do not need C unless allocations use hot-drop mode. POST /keys/pull and POST /keys/export are not a storefront profile: they are for moving purchased keys into your own warehouse or vault in bulk, outside a buyer checkout. Promotions are an add-on to any profile (Promotions).


The easy path (all profiles)#

Diagram

Rules every store must follow:

  1. Server-to-server only — never put API keys in a browser or mobile app.
  2. Do not charge unless canFulfill is true on preview (or availability with quantity).
  3. POST /orders is all-or-nothing — no partial keys. A shortfall is a 409: NO_AVAILABLE_KEYS when the vendor's stock is empty, ALLOCATION_EXCEEDED when your allocation cap is reached (details.remainingInAllocation; request more with POST /allocations/requests). Either way nothing was delivered → refund at your PSP.
  4. Reuse the same Idempotency-Key when retrying the same checkout; use a new key only for a new purchase.
  5. Set orderReference to your store order id on every POST /orders.
  6. Echo expectedUnitPriceCents from preview on every commercial commit (API business model — territory catalog list price). Prefer placeStoreOrderFromPreview, which also forwards priceCommitmentToken when preview returns one.
  7. Persist keys from the POST /orders response — webhooks are metadata-only.
  8. Treat region locks as geo-unverified until whoami.capabilities.consumerGeoEnforcementEnabled is true — Territory enforcement.
  9. Prefer the reference helper patterns (createSellerClient, syncSellableCatalog, checkout + webhook consumer) over ad-hoc fetch — Client and helpers.

Profile A — Minimal store#

For: first integration, low traffic, proving checkout end-to-end.

StepAPINotes
1GET /whoamiConfirm scopes, BMA (hasActiveBma), capabilities
2GET /products?limit=50Pick skuCode from detail if needed
3GET /allocationsKeep only rows with sellable: true
4POST /orders/previewGate Pay on canFulfill
5Your PSPAvrix never charges the buyer — you capture payment
6POST /ordersIdempotency-Key + orderReference

Scopes: seller:products:read, seller:keys:pull (preview accepts seller:orders:preview or seller:keys:pull).

Defer until later: hot-drop, bulk orders, finance reads, checkout hold.

Recipe: Integration recipes — browse-catalog + create-order.
Postman: folder Store profile A — minimal checkout (preview → order).
Code: checkout helpers — see Client and helpers.


Profile B — Production store#

For: live storefronts with catalog sync and operational safety.

Everything in Profile A, plus:

AdditionAPI / eventWhy
Sellable catalog syncsyncSellableCatalog + syncCatalogChangesSnapshot alone ≠ sellable — merge /allocations (Sellable SKU readiness)
Cart stock checkGET /availability?skuCode=…&quantity=NcanFulfill without posting preview on every keystroke
Catalog pushWebhooks product.updated, allocation.updated, allocation.low_stock, product.delistedAvoid stale “in stock” UI
Fulfillment pushWebhook order.fulfilled / order.reserved / order.failedLifecycle/metadata only — persist keys from POST /orders response; use createWebhookConsumer
ReconcileGET /orders?orderReference=…Support and finance alignment
Soft holdPOST /orders/hold → checkoutHoldId on POST /ordersCheck whoami.capabilities.checkoutHoldEnabled — Order preview
Backorder fallbackbackorderOnUnavailable: true on POST /orders; webhooks order.ready / order.backorder_expiredA stock-out after payment becomes awaiting_stock instead of a refund; fulfil on order.ready, refund on order.backorder_expired (default 14 days) — Order lifecycle

Recipe: check-before-pull, webhooks, get-order. Helpers: checkout helpers — see Client and helpers.

Rehearse the whole profile against the shared sandbox catalog before you point it at live inventory — see Sandbox and environments.


Profile C — Launch / high contention#

For: drop-day traffic on allocations with hot_drop_mode.

Everything in Profile B, plus:

StepAPIFallback
ReservePOST /orders/reserve412 HOT_DROP_NOT_ENABLED → use Profile B (POST /orders only)
CommitPOST /orders/commit before TTL expiresSeconds-level window — see OpenAPI for reserve/commit TTL

Checkout soft-hold is separate from hot-drop: normal allocations use hold; hot-drop allocations use reserve/commit.


Common mistakes#

Do notDo instead
Charge when canFulfill is falseDisable Pay; show out of stock
Expect partial keys on POST /ordersTreat 409 as zero keys; refund at PSP
Retry POST /orders with a new idempotency key for the same saleSame key as first attempt
Poll GET /products on every page viewWebhooks + updatedSince / snapshot
Call POST /orders to “get a price”POST /orders/preview only
Skip Profile B sync and list every catalog SKUMerge allocations (sellable: true) before merchandising

After payment failure#

Send backorderOnUnavailable: true on POST /orders (on by default unless the Content Owner opted out) and a vendor stock-out after payment becomes a backorder (awaiting_stock) instead of a 409: keep the payment, fulfil on order.ready, and refund only on order.backorder_expired.

If POST /orders still returns 409 NO_AVAILABLE_KEYS (vendor stock empty, backorder not requested or not allowed) or ALLOCATION_EXCEEDED (your allocation cap reached) after the buyer paid:

  1. Log X-Request-Id / requestId.
  2. Refund at your PSP (Avrix does not auto-refund external checkouts). Nothing was delivered.
  3. Read details.recommendedAction (refund_customer, or request_allocation_increase for ALLOCATION_EXCEEDED: file POST /allocations/requests so the next buyer can be served) — Error playbook.

If it returns a 5xx or times out after the buyer paid, do not refund yet: retry with the same Idempotency-Key and orderReference first (error playbook).


Next steps#

DocTopic
30-minute quickstartEnd-to-end golden path
Order previewPreview fields and price binding
Integration recipesScopes, call order, idempotency
Error playbookRecovery actions after failed checkout
SDK & helpersTyped client and checkout helpers
Monitoring and supportStatus page and the service levels we measure

What links here

Published guides that link to this page.

Search docs

Search documentation…