Seller API overview

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.

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

• 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.

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.

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

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:

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

• 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.

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.

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

• 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

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

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

• 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.