Seller API overview

What the Seller API does, who it is for, and the golden-path integration shape.

The Avrix Seller API lets your storefront sell digital game entitlements that vendors have allocated to you. You keep your own checkout, your own payment processor, and your own customer relationship. Avrix supplies the catalog, guarantees inventory under your agreements, and delivers the entitlement when you confirm the sale.

Who needs this#

Anyone evaluating or starting a Seller API integration — store backends, keyshops, and partner engineers who need the commercial model before writing checkout code.

TL;DR#

  • You charge the buyer at your PSP; Avrix fulfils wholesale entitlements and never auto-refunds retail.
  • A SKU is sellable only when four gates are open: BMA → share → allocation → territory pricing.
  • Golden path: sync catalog + allocations → preview (canFulfill) → charge → POST /orders with a stable Idempotency-Key → persist keys from the HTTP response.
  • Access is sales-led: contact Avrix, build in sandbox, certify, then get production enabled.

Getting access#

Seller API access is sales-led, not anonymous self-serve:

  1. Contact Avrix (your partner manager, or support@avrix.io) to request a seller company account.
  2. Avrix provisions your Console company and invites your admins.
  3. Create a Sandbox API key under Settings → Integrations → API Keys and build against the shared sandbox catalog.
  4. Complete Certification and submit evidence to your Avrix contact.
  5. Sign the API Revenue Share Channel Terms in Settings → Commercial Agreements. Until you do, the Console will not mint a production key (403 API_MODEL_AGREEMENT_REQUIRED if you try via POST /keys).
  6. Avrix enables production API access on your company. Until then, production keys on api.avrix.io return 403 PRODUCTION_ACCESS_NOT_APPROVED. Sandbox keys continue to work.
  7. Create a Production key, finish Go-live, and cut over.

You need at least one active vendor agreement (BMA) before production catalog and orders are useful. Sandbox uses a shared fixture catalog so you can integrate before real BMAs exist.

Who is involved#

PartyRole
VendorThe content owner — the studio or publisher that owns the game and the keys. Marketed as Content Owner.
SellerYou — the storefront that sells to the end buyer. Marketed as Content Seller.
AvrixThe platform that holds agreements, catalog, and inventory, and enforces commercial terms between vendor and seller.

You integrate with Avrix once. Every vendor you have an agreement with becomes available through the same API.

Four sellability gates#

In plain English: the vendor must agree to trade with you, share the SKU, give you capacity, and price the buyer’s country. All four must be open before a SKU is sellable:

Diagram

A SKU can appear in catalog browse and still not be sellable. Merge catalog feeds with GET /allocations (sellable: true) — see Catalog and allocations.

Money flows#

  • You and your buyer. You set the retail price, charge through your PSP, and own refunds. Avrix never charges or refunds your buyer.
  • You and Avrix. Each fulfilled order records a wholesale sale at contracted terms for settlement.

Golden path#

Diagram
  1. Authenticate with a Seller API key.
  2. Sync catalog (products / snapshot) + allocations → sellable set.
  3. Preview the order (canFulfill: true).
  4. Charge the buyer at your PSP.
  5. Create the order with a stable Idempotency-Key.
  6. Persist the entitlement from the HTTP response (webhooks never include plaintext keys).
  7. Consume webhooks and run reconciliation.

Fulfilment#

Successful POST /orders returns plaintext keys in the response (deliveryMode: "key"). Persist them immediately — GET /orders and webhooks never include key plaintext.

What Avrix does not do#

  • Charge your buyer, hold retail funds, or process PSP refunds
  • Set your retail price
  • Re-deliver key plaintext via GET /orders or webhooks
  • Partially fulfil an order (all-or-nothing)
  • Calculate your taxes

Environments and key prefixes#

SandboxProduction
PurposeBuild and certifyLive sales
CatalogShared fixture catalog with magic SKUs (e.g. SANDBOX-ALWAYS-001)Your real agreements
Key materialTest keysReal keys

New secrets use environment-aware prefixes (cosmetic; auth is hash-based):

Key typeExample prefix
Liveavrix_sk_live_…
Sandboxavrix_sk_sbx_…

Legacy plain avrix_sk_… keys remain valid until rotated. Environment on the key record is authoritative — mismatches return KEY_ENVIRONMENT_MISMATCH.

Common mistakes#

  • Listing catalog SKUs without checking GET /allocations (sellable: true).
  • Charging the buyer when preview canFulfill is false.
  • Retrying a timed-out POST /orders with a new Idempotency-Key (creates a second fulfilment risk).
  • Expecting plaintext keys on webhooks or GET /orders.

Next steps#

You areStart here
Requesting an accountGetting access
Evaluating the commercial modelHow Avrix works
Building the first integrationIntegration tutorial
Implementing checkoutCreating orders, Order lifecycle
Breaking-change policyVersioning and compatibility
Security reviewSecurity, Authentication

What links here

Published guides that link to this page.

Search docs

Search documentation…