Use this guide when wiring a test connection: it defines the public host, authentication, and how to interpret 401/403 so you do not mistake configuration for a successful API response.
Example#
curl -s -X GET "https://api.avrix.io/api/seller/v1/whoami" \
-H "Authorization: Bearer $AVRIX_API_KEY"One host model#
Integrators use a single public Seller API host. The API key environment
(sandbox vs production) selects behaviour — not a separate hostname.
| Dimension | Sandbox key | Production key |
|---|---|---|
| Base URL | https://api.avrix.io | https://api.avrix.io |
| Console | https://app.avrix.io | https://app.avrix.io |
| Catalog | Fixture catalog with magic SKUs (shared, or your store's isolated environment) | Your real agreements and allocations |
| Key material | Test keys | Real keys |
| Commercial evidence | The settlement declarations (see What each key must declare) | The settlement declarations plus the full commercial evidence |
All Seller API routes are rooted at /api/seller/v1/ (versioned); unversioned paths redirect
there (which paths, from which contract date). Health check: GET /api/seller/v1/health.
Environment matrix (keys)#
| Rule | Detail |
|---|---|
| Key determines environment | A sandbox key never acts as production inventory; a production key never accepts magic SKUs. |
| Same host | Call https://api.avrix.io for both. KEY_ENVIRONMENT_MISMATCH means a production key sent X-Avrix-Sandbox: true, or a sandbox key reached a deployment with the sandbox disabled. |
| Support | When opening a ticket, include requestId / X-Request-Id and whether the key was sandbox or production. See Monitoring and support. |
Troubleshooting — wrong key vs wrong config#
| Symptom | Likely cause | Fix |
|---|---|---|
401 Invalid API key | Wrong secret, revoked/rotated key, or typo | Recreate / re-copy from Settings → Integrations → API Keys |
401 API key expired | The key's expiry has passed (keys minted via POST /keys take the expiresAt sent, or the parent key's expiry) | Create a new key; console-created keys have no expiry. api_key.expiring warns 14 days ahead |
| 401 KEY_ENVIRONMENT_MISMATCH | A production key sent with X-Avrix-Sandbox: true, or a sandbox key used on a deployment where the sandbox is disabled | Drop the header from production calls; use a production key on that deployment. GET /whoami shows data.key.environment and requestEnvironment |
| 403 IP_NOT_ALLOWED | Egress IP not on the key allowed_ips list | Add your IP/CIDR in Settings → Integrations → API Keys, or test from an allowed network |
| Key works from your laptop but not from your server | Allowlist and/or wrong secret in that environment | Run GET /api/seller/v1/whoami-ip from the same egress |
Sandbox mode#
Sandbox lets you exercise deterministic catalog SKUs and fulfillment paths without touching your
live inventory. The sandbox runs on https://api.avrix.io; with a sandbox key,
GET /api/seller/v1/whoami returns a sandboxCatalog block. A deployment that does not run the
sandbox refuses sandbox keys with 401 KEY_ENVIRONMENT_MISMATCH, so that is the answer to "is the
sandbox enabled here".
To use it:
- Create a Sandbox key in Settings → Integrations → API Keys (environment toggle).
- Call
https://api.avrix.iowith the sandbox key —X-Avrix-Sandbox: trueis optional when sandbox is enabled (header still supported for explicit debugging). - Exercise the sandbox catalog with deterministic magic SKUs — your real company inventory is never touched. The catalog is the shared sandbox catalog until Avrix moves your store to its own isolated environment (see Isolated store environments below).
GET /whoami returns sandboxCatalog (magic SKUs, tenantReady, headerRequired) when using
a sandbox key. The tenantReady field is part of the API response shape — when true, the shared
sandbox catalog is ready for requests.
Console Settings → Integrations → API Keys → Sandbox developer tools runs the golden path and shows per-key request logs and webhook deliveries.
Shared sandbox catalog caveats
Until your store runs in its isolated environment (next section), all sandbox keys route to the same shared sandbox catalog, allocations, and key pools:
SANDBOX-ALWAYS-001 and SANDBOX-EUR1-001 are also in launch mode (hotDropMode: true), so you can
rehearse POST /orders/reserve and POST /orders/commit on them. See
Stock and reservations.
| Concern | Behavior | Mitigation |
|---|---|---|
| Key pool contention | Heavy parallel testing on SANDBOX-STD-001 can exhaust the finite pool → 409 NO_AVAILABLE_KEYS until pools are replenished | Default to SANDBOX-ALWAYS-001 for CI, Postman, and load tests |
| Order isolation | GET /orders is scoped per API key — integrators cannot read another sandbox key's orders by reference | Use unique orderReference values |
| Catalog visibility | All integrators see identical products, availability, and allocation counts | Expected for the shared sandbox catalog; webhooks remain per-key |
| Shared settings | PUT /me/footprint and PATCH /allocations/{id} change what every integrator on the shared sandbox sees. On contract date 2026-12-01 and later they answer 422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED there; on earlier dates they still run | Rehearse them in your store's isolated environment |
Isolated store environments
Avrix is moving each store to its own isolated sandbox environment: a separate sandbox Content Seller and Content Owner pair with its own catalog, agreements, allocations, stock pools and fault scenario state. Every sandbox key of your store runs in the same environment; orders, idempotency keys and webhook endpoints stay scoped per API key inside it. Production keys are not affected.
- Your stock is yours. Other integrators cannot deplete your pools, so
SANDBOX-STD-001and the other finite fixtures behave the same on every run.SANDBOX-LOWSTOCK-001is still pinned at 3 keys andSANDBOX-NOKEYS-001is still empty. - Public fixture codes do not change. You keep sending
SANDBOX-ALWAYS-001,SANDBOX-STD-001and the other codes in the table below, and every response, export, catalog snapshot and webhook payload shows the same public codes. Internal SKU codes of your environment never appear. - Ids are per environment. Product, SKU and allocation ids in your environment differ from the shared sandbox catalog and from every other store's environment. An id from another environment is not found in yours, even when its public fixture code matches.
- Catalog events are your environment's.
product.*,sku.*,release.*andcontract.*events describe your environment's catalog and go only to your store's sandbox endpoints. Commerce events (order.*,keys.*,allocation.*,refund.*) still go only to the endpoints of the key that caused them. - Generated product media is not copied. Cover art and screenshots exist on the shared sandbox catalog only; the rest of the catalog data has the same shape.
Moving a store. Creating a sandbox key queues your store's environment, and Avrix builds it in
the background. Avrix then moves the store (the cutover) once the environment is ready. The move is
one-way and applies to all sandbox keys of the store at once. GET /sandbox/certification reports
data.environment.mode: shared before the move, isolated after it.
After the move, resync your catalog. Product, SKU and allocation ids change at the cutover; no
live (production) ids change. Take a fresh GET /catalog/snapshot and replace the sandbox ids you
stored. A GET /catalog/changes or GET /availability/changes call with a cursor from the shared
feed, or a since from before the move, answers 409 CATALOG_RESYNC_REQUIRED.
What stays the same across the move:
- Your webhook endpoints keep their ids and signing secrets.
- A retry with the same
Idempotency-Keyand body replays the original response. - Orders placed before the move stay reachable by the key that created them through the key-scoped
operations:
GET /orders/{orderId}, lookup byorderReference, fulfil, key replacement,POST /orders/recover-keys, refunds by order or by refund id, dispute freeze and release, and keyless management. Lists and reports (GET /orders, transactions, finance), cancel,POST /keys/return, chargebacks and hot-drop extend serve the new environment only.
When the environment is not usable. While your environment is being prepared or repaired,
sandbox requests answer 503 SANDBOX_ENVIRONMENT_UNAVAILABLE with Retry-After (and details.retryAfterSeconds);
they are never sent to the shared catalog or to production inventory instead. When Avrix pauses
writes for a repair, writes answer 503 SANDBOX_ENVIRONMENT_PAUSED and reads keep working. See
the Error reference.
Magic SKUs (sandbox catalog only)
| SKU code | Scenario |
|---|---|
SANDBOX-STD-001 | Standard happy-path fulfillment |
SANDBOX-ALWAYS-001 | Large replenished pool (never runs dry) — default for Postman / smoke tests |
SANDBOX-EUR1-001 | €1.00 EUR catalog price for live PSP dogfood (your processor’s test mode); large replenished pool — use countryCode DE / FR / NL and expectedUnitPriceCents 100 (prefer preview-chained) |
SANDBOX-NOKEYS-001 | 409 NO_AVAILABLE_KEYS |
SANDBOX-TERR-BLOCK-001 | Territory blocked (price list DE-only; use US in tests) |
SANDBOX-ACTIVATION-LOCK-001 | Activation locked to Germany (keys only activate in DE; preview, hold and commit with US refuse with ACTIVATION_REGION_MISMATCH) |
SANDBOX-BACKORDER-001 | Never in stock (backorderOnUnavailable: true returns awaiting_stock; order.backorder_expired after 15 minutes) |
SANDBOX-REPLACE-PENDING-001 | Key replacements wait for the Content Owner (POST /orders/{orderId}/keys/{keyId}/replace answers 202 pending); approved a moment later, then key.replaced |
SANDBOX-REVOKE-001 | Keys are revoked right after delivery (reason leaked); keys.revoked arrives with recommendedAction: replace |
SANDBOX-PRICE-MIS-001 | Catalog price $59.99 — wrong expectedUnitPriceCents → mismatch |
SANDBOX-NOALLOC-001 | Share without allocation → sellable: false, readiness NO_ALLOCATION |
SANDBOX-NOSHARE-001 | No seller share — not in partner catalog; order by skuCode fails entitlement |
SANDBOX-LIFECYCLE-001 | Shared/allocated but product not live → PRODUCT_NOT_SELLABLE |
SANDBOX-LOWSTOCK-001 | Pool pinned at 3 keys — test partial availability and bulk strict semantics; quantity above stock → 409 NO_AVAILABLE_KEYS |
SANDBOX-PREORDER-001 | Pre-order lifecycle (releases 2027-03-25; pre-order window open). Preview answers fulfillmentType: "pre-order", and POST /orders accepts the order as awaiting_release without keys (pre-orders) |
SANDBOX-WHOLESALE-MIS-001 | Wholesale-model allocation priced 2500 — any other expectedUnitPriceCents → WHOLESALE_PRICE_MISMATCH |
SANDBOX-CHURN-001 | Rotates live ↔ delisted every 6 hours — poll GET /catalog/changes for added / removed tombstones |
SANDBOX-PROMO-001 | Carries the sandbox promotions: a live deal, an upcoming deal, a deal waiting for your answer and an event share waiting for your answer (see Rehearsing vendor actions below) |
SANDBOX-REFUND-EXPIRED-001 | Refund window of 0 days: POST /refunds for a key sold on it answers 422 REFUND_WINDOW_EXPIRED |
SANDBOX-REDEEMED-001 | Keys are marked redeemed right after delivery: POST /refunds or POST /keys/return for them answers 409 KEY_NOT_RETURNABLE |
SANDBOX-ALLOC-REQUEST-001 | An allocation of 5 over 30 keys in stock: POST /allocations/requests for more waits for the vendor, and the sandbox vendor can approve it (see Rehearsing vendor actions below) |
Sandbox keys also accept three TEST-NET consumer IPs (listed on GET /whoami → sandboxCatalog.magicConsumerIps) so you can exercise geo and buyer-risk failures without production geo data. Production keys still reject these as reserved (CONSUMER_IP_INVALID).
| Consumer IP | Expected outcome on preview / reserve / hold / commit |
|---|---|
203.0.113.66 | 422 CONSUMER_GEO_MISMATCH |
203.0.113.99 | 422 CONSUMER_IP_HIGH_RISK |
203.0.113.77 | 422 CONSUMER_RISK_HIGH (buyer risk score refusal; no provider is called in sandbox) |
The sandbox catalog is seeded production-real so your parsing code sees the same shapes as live
data: localized store descriptions in six languages, genres and age ratings, cover art and
screenshots, per-country price lists (USD, GBP, EUR, PLN, BRL, JPY, CAD, AUD), Steam external
references, and multi-platform releases. Flagship products also expose per-platform SKUs
(SANDBOX-STD-PS5-001, SANDBOX-STD-XSX-001, SANDBOX-ALWAYS-EPIC-001, SANDBOX-ALWAYS-PS5-001,
SANDBOX-ALWAYS-SWITCH-001, SANDBOX-EUR1-EPIC-001, SANDBOX-PREORDER-PS5-001) so multi-platform
catalog sync can be exercised end to end.
Magic order references (sandbox_order_*) and payment refs (sandbox_pay_*) are rejected on
production keys with 422 SANDBOX_MAGIC_VALUE_REJECTED.
Per-key environment#
Each API key carries an environment of production or sandbox (default production).
Mismatched key environment vs request returns HTTP 401 with code: "KEY_ENVIRONMENT_MISMATCH"
and details: { keyEnvironment, requestEnvironment }. With one host and no environment parameter,
the request environment differs from the key's in only two cases: a production key sent with
X-Avrix-Sandbox: true, and a sandbox key on a deployment where the sandbox is disabled.
Token prefix (recognition only)
New and rotated secrets encode key type in the token itself. Auth looks keys up by hash; the
Console environment badge and GET /whoami remain authoritative.
| Key type | Example prefix |
|---|---|
Live (production) | avrix_sk_live_… |
| Sandbox | avrix_sk_sbx_… |
Pre-existing keys may still show the legacy avrix_sk_… shape until rotated. The console
environment badge remains the source of truth when the prefix is ambiguous.
Matching rules on https://api.avrix.io:
| Sandbox availability | X-Avrix-Sandbox: true? | Allowed key environment(s) |
|---|---|---|
| Sandbox enabled | no | sandbox keys allowed without header |
| Sandbox disabled | no | production only |
| Sandbox enabled | yes | sandbox only |
Webhook isolation (shared sandbox catalog)
Sandbox webhook endpoints are scoped by API key. Each integrator only lists, receives, and mutates webhooks created with their sandbox key.
Isolation is enforced fail-closed. Commerce events (order.*, keys.*, allocation.*,
refund.*, invoice.*, report.*) are delivered only to endpoints belonging to the API key that
caused them; if an event cannot be attributed to a key, it is dropped rather than fanned out.
Shared-catalog events (product.*, sku.*, release.*, contract.*) describe the shared sandbox
catalog and are delivered to all sandbox endpoints subscribed to them.
Two consequences in sandbox only (production deliveries behave normally):
- Platform-driven events with no originating key — for example the pre-order fulfilment cron —
are not delivered. Poll
GET /ordersto observe those transitions in sandbox. - Vendor-console actions against the shared sandbox catalog (for example a manual allocation edit)
do not emit
allocation.updated. Pulls and returns made with your own sandbox key DO emitallocation.updated(reasonspulled/returned), and share-scope changes emitsku.sellability_changed, so a store can exercise both handlers in sandbox.
Simulate headers (sandbox only)
| Header | Effect |
|---|---|
X-Avrix-Sandbox-Simulate: rate_limit | Returns 429 RATE_LIMIT_EXCEEDED (Retry-After: 2) |
X-Avrix-Sandbox-Simulate: hot_path_timeout | Returns 504 HOT_PATH_TIMEOUT (Retry-After: 1); nothing pulled |
X-Avrix-Sandbox-Simulate: key_decrypt_failed | Returns 503 KEY_DECRYPT_FAILED (Retry-After: 5); nothing pulled |
X-Avrix-Sandbox-Simulate: billing_record_failed | Returns 503 BILLING_RECORD_FAILED (Retry-After: 5); nothing pulled |
X-Avrix-Sandbox-Simulate: internal_error | Returns 500 INTERNAL_ERROR |
X-Avrix-Sandbox-Simulate: service_unavailable | Returns 503 SERVICE_UNAVAILABLE (Retry-After: 5); nothing pulled — rehearse a database or dependency outage |
X-Avrix-Sandbox-Simulate: idempotency_in_flight | Returns 409 IDEMPOTENCY_REQUEST_IN_FLIGHT (Retry-After: 5) |
X-Avrix-Sandbox-Simulate: webhook_delay_30s | Delays the first webhook delivery attempt by 30 seconds |
X-Avrix-Sandbox-Simulate: buyer_verification_required | Checkout behaves as if the Content Owner required the buyer network confirmation: without a completed attestId the call answers 422 CONSUMER_GEO_ATTEST_REQUIRED and nothing is pulled |
Which operations honour which value:
- Checkout writes.
POST /orders,POST /orders/bulk,POST /orders/commitandPOST /keys/pullhonour every write-path mode (rate_limit,hot_path_timeout,key_decrypt_failed,billing_record_failed,internal_error,service_unavailable,idempotency_in_flight). They fail before inventory work: retry the sameIdempotency-Keywithout the header. - Every other write (refunds, returns, cancellations, holds, reservations, allocation and
webhook changes, and the rest) honours
rate_limit,internal_errorandservice_unavailable, answered before any work. This includesPOST /orders/cancel,POST /orders/recover-keys,POST /keys/export,POST /keys/return,POST /refundsandPOST /chargebacks/resolve, which ignored the header before, so you can rehearse the retry logic of every write. - Reads honour
rate_limit. buyer_verification_requiredis honoured byPOST /orders,POST /orders/bulk,POST /orders/commit,POST /keys/pull,POST /orders/hold,POST /orders/previewandPOST /orders/reserve. Rehearse the whole path: mint an attestation withPOST /geo/attest, have the buyer's browser complete it, read its state withGET /geo/attest/{attestId}, and resend the order with theattestId. See Territory enforcement.
The API reference declares on each operation exactly the values it honours.
A value the operation does not honour. On contract date 2026-12-01 and later (and next), a
sandbox key's call with a misspelt value, or a value that belongs to another operation, answers
422 SANDBOX_SIMULATE_UNKNOWN before any work, with the values that operation honours in
details.honoured. On earlier dates such a value is ignored, as it always was. A production key's
header is ignored on every date.
Stateful fault scenarios
The same header also takes five stateful scenarios for rehearsing recovery. Unlike the modes
above, which fail every request, a scenario fails only the first attempt of an idempotent
request; the retry with the same Idempotency-Key and body recovers. Scenarios run only in your
store's isolated environment, because their state is kept per environment.
X-Avrix-Sandbox-Simulate | Route | First attempt | Retry with the same key and body |
|---|---|---|---|
timeout_then_success | POST /orders | 504 HOT_PATH_TIMEOUT (Retry-After: 1) before anything is committed | Placed once, normally |
error_after_commit | POST /orders | The order is committed and its idempotent result stored, then the response is replaced by 500 INTERNAL_ERROR | Replays the original order (Idempotency-Replayed: true); no second pull |
webhook_delay_duplicate | POST /orders | Succeeds; order.fulfilled is delivered 30 seconds late and twice with the same eventId | Replays normally |
partial_cart | POST /orders/bulk | The SANDBOX-LOWSTOCK-001 pool is reset to exactly 3 keys before the order, so a cart that asks for more shows the real partial or strict line outcomes | Replays normally |
sold_out_after_hold | POST /orders/hold | The hold succeeds and the response describes it; right after, the hold is released and your environment's remaining stock of that SKU is blocked | Committing that hold, or previewing the SKU, sees a sold-out SKU |
- A run is keyed by your environment, API key, scenario and
Idempotency-Key. A newIdempotency-Keystarts a new run; concurrent attempts are counted atomically, so only one attempt gets the fault. - Runs expire after one hour. Stock blocked by
sold_out_after_holdis then given back to your pool. - Fault responses carry
details.simulatewith the scenario name. No scenario changes another store's environment or any production data. - On the shared sandbox catalog, and for
partial_cartorsold_out_after_holdonPOST /orders, the request answers 422SANDBOX_SCENARIO_UNAVAILABLE. Production keys ignore the header.
error_after_commit is the scenario to rehearse first: the order exists although your client saw
a 5xx, and the only correct recovery is the retry with the same key and body, not a refund. See
A 5xx after you charged the buyer.
Rehearsing vendor actions
Some flows start with a Content Owner acting: approving an allocation request, sending a deal, starting a promotion, offering wider access. The sandbox vendor does these for you, so you can rehearse your handlers without waiting for a person. Every sandbox environment (the shared sandbox and isolated ones) is seeded with:
- Promotions on
SANDBOX-PROMO-001: a live deal and an upcoming deal you have approved, a deal waiting for your answer (POST /promotions/deals/{responseId}/respond), and an event share waiting for your answer (POST /promotions/shares/{shareId}/acceptor/decline). - A closed refund window on
SANDBOX-REFUND-EXPIRED-001and keys redeemed after sale onSANDBOX-REDEEMED-001, so the refund and return refusals can be reproduced. - An access proposal, in isolated environments only: the sandbox vendor removes one currency
your sandbox store does not sell in and offers it back, so
GET /access/proposalslists a proposal you can accept or decline. On the shared sandbox, accepting it would change the agreement of every store on it.
The sandbox controls are sandbox-only operations under /sandbox. A production key answers
422 SANDBOX_KEY_REQUIRED and nothing is read or changed. Controls that change data every store
on the shared sandbox reads answer 422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED there.
| Control | What it does | Shared sandbox |
|---|---|---|
POST /sandbox/allocations/requests/{requestId}/resolve | The sandbox vendor approves or declines your pending allocation request; you receive allocation.request_decided (and allocation.updated on approval). Approvals follow the production stock rule: rehearse them on SANDBOX-ALLOC-REQUEST-001. | Decline only |
POST /sandbox/allocations/{allocationId}/stock-events | Sends allocation.low_stock or allocation.depleted for one of your allocations without selling anything. | Yes |
POST /sandbox/promotions/deals/{responseId}/window | Moves a deal the vendor sent so it starts now or ends now; an approved deal sends promotion.started or promotion.ended. | No |
POST /sandbox/reset | Puts your isolated environment back in a known state (see below). | No |
Reset. POST /sandbox/reset expires open fault scenarios and releases the stock they held,
cancels pending allocation requests, restores the selling footprint, tops up every fixture pool,
brings the SANDBOX-ALLOC-REQUEST-001 allocation back to 5 unsold units, and re-arms the rehearsal
fixtures (the event share is pending again, missing deals are re-created, the refund window is
restored and a new access proposal is offered if none is open). Orders, keys already sold, refunds
and finance records are kept. An environment built before a fixture existed lists it in
data.missingFixtures; Avrix adds it when it next repairs the environment.
There is no clock control: deals move with the window control above, and time-based jobs (expiry, statements) run on their normal schedule.
Test-fire any webhook event
POST /webhooks/{id}/test with a sandbox key accepts an optional JSON body:
{"eventType": "order.fulfilled", "challenge": "invalid_signature"}. eventType is any Seller
API event (default test.ping), sent with a contract-valid sample payload through the normal
signing and delivery pipeline. challenge turns the delivery into a receiver test: valid,
invalid_signature, stale_timestamp, duplicate or previous_secret_only. Every test delivery
other than a plain test.ping carries a top-level testEvent object, so your handler can tell it
from real traffic. Production keys can send test.ping only. Details:
Webhooks.
Certification report
GET /sandbox/certification evaluates the 28 certification cases from your sandbox key's own
traffic over the last 30 days and returns pass, fail, not_run or needs_partner_evidence
for each, with the request and delivery ids behind it, and notCovered: the areas the cases do
not certify (promotions, finance statements, key management, allocation requests, partner access),
each with the reason. Sandbox keys only. See Certification.
This blocks two common foot-guns: deploying a sandbox key into production traffic, and pointing a production key at a sandbox-only posture without understanding the key environment.
Production key vs sandbox key (integrationOrderContext)#
What each key must declare in integrationOrderContext on the operations that deliver keys
(POST /orders, commit, bulk, keys pull and export). GET /whoami returns the same list for the
calling key at data.requiredDeclarationsByOperation; the full field contract is in
Order context.
| Required on every key (sandbox and production) | Required on production keys only | Optional |
|---|---|---|
schemaVersion, salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent, salesChannel | currencyCode, salesPriceNetMinor, priceIncludesTax, salesTaxAmountMinor, paymentMethodFamily, paymentProcessorReference, checkoutSessionId, consumerIp | Every other field, unless a strict profile on the key adds it |
Sandbox keys may send the production-only fields and should: it is the cheapest rehearsal of the
cutover. Fixture values such as sandbox_pay_* are accepted on sandbox keys and refused on
production keys (SANDBOX_MAGIC_VALUE_REJECTED).
See Integration recipes for how to send integrationOrderContext on
store orders.
Quick sandbox path (self-service)#
- In the console: Settings → Integrations → API Keys → Create key → Environment: Sandbox.
- Confirm the sandbox is ready for that key —
GET /api/seller/v1/whoamireturnssandboxCatalogwithtenantReady: true. - Call
https://api.avrix.iowithAuthorization: Bearer <sandbox_key>(optionallyX-Avrix-Sandbox: true). - Golden path:
GET /health→GET /whoami→GET /products→POST /orders/preview→POST /orders→GET /orders. Start with Quickstart for the full narrative (~15 minutes).
Magic SKU SANDBOX-ALWAYS-001 is the recommended default for smoke tests; SANDBOX-STD-001
is fine for light manual trials. For live PSP dogfood (~€1 catalog bind), use
SANDBOX-EUR1-001 with countryCode DE / FR / NL.
Authentication#
-
In the Avrix console, open Settings → Integrations → API Keys (seller company).
-
Create a key and assign scopes for the recipes you need (see Scope matrix).
-
Send every request with:
HTTPAuthorization: Bearer <your_seller_api_key>
Keys with null or empty scopes are refused with 403 (details.reason: "scopes_required"; code FORBIDDEN, or INSUFFICIENT_SCOPE on contract date 2026-12-01 and later). They are not full access.
Always create keys with the scopes you need.
Scopes and 403#
| Symptom | Likely cause | What to do |
|---|---|---|
| 403 with message about missing scope | Key does not include a scope the operation accepts (e.g. seller:orders:write for orders). | Create a new key with the right scopes. See Scope matrix. |
| 401 | Missing/invalid Authorization, wrong key format, expired, or revoked key. | Verify Bearer prefix, no extra quotes, key environment. See Error playbook. |
| 403 from IP allowlist | Key has allowed_ips configured and your egress IP is not listed. | Add your IP in Settings → Integrations → API Keys. See IP allowlist. |
Do not treat a 401/403 as “success” or mock a JSON body to continue development — fix auth, scopes, or network first.
Correlation and support#
- Every response includes
X-Request-Idwhen the API sends standard headers. Always log it when reporting issues. - Error bodies may include
requestId,code,hint, anddoc_url. Prefer first failing request in a trace when debugging (not only the last error). - Escalation: Monitoring and support.
Optional: CORS#
If browser CORS origins are configured on the deployment, browser clients receive CORS headers.
Allowed methods are GET, POST, PUT, PATCH, DELETE and OPTIONS.
Server-to-server (Postman, curl, backend) does not require CORS.
Rehearsing the commercial refusals#
The sandbox contract is deliberately configured with the suggested term values, so it behaves like a newly signed agreement: vat_basis: purchaser_country_capped, permitted_sale_currencies: primary_only, permitted_sales_channels: own_storefront, geo_mismatch_policy: warn.
That makes four of the commercial refusals reproducible here with nothing but a request body, and three of them unreachable. Both halves are worth knowing.
Reproducible in sandbox#
| To see | Send |
|---|---|
SALES_CHANNEL_REQUIRED | An order with no integrationOrderContext.salesChannel. |
SALES_CHANNEL_NOT_PERMITTED | salesChannel: "marketplace:steam". Any marketplace:<slug> is outside own_storefront. |
FOOTPRINT_COUNTRY_NOT_DECLARED | salesCountryCode: "MX" (or SE, NO, CH). The sandbox store declares US, CA, GB, DE, FR, NL, PL, ES, IT, HU, BR, JP and AU, so anything else is outside its footprint. |
CURRENCY_NOT_PERMITTED_BY_TERM | A currencyCode that is not the SKU's own currency for that country, for example EUR on a USD-priced country. Under primary_only only each country's own currency is permitted. |
Not reproducible in sandbox, and why#
CURRENCY_NOT_PRICED_FOR_COUNTRY and CONSUMER_GEO_MISMATCH_POLICY_REFUSED cannot be triggered here. Both need values the sandbox does not use: the first needs an agreement permitting more than each country's own currency, or a Content Owner who no longer allows the currency a country is priced in, and the second needs a geo_mismatch_policy of refuse rather than warn.
We have not added fixtures for them, because a sandbox contract configured to demonstrate every refusal would no longer resemble the agreement you are actually going to sign, and rehearsing against a contract nobody has is worse than not rehearsing. Handle the codes from the error playbook; each states what causes it and what to do.
The same is true of the two advanced settlement modes. A permitted_sale_currencies of custom (a named currency list per country) and a permitted_sales_channels of own_storefront_plus_named_marketplaces (specific marketplaces by slug) are not configured on the sandbox agreement, so the refusals they produce cannot be rehearsed here either. When your own agreement states one of them, GET /whoami names the currencies and channels it permits, and the Commercial Schedule you signed lists them in full.
GET /whoami reports which of these apply to you, so you can tell before you send an order.
What sandbox gives you#
Required declarations on API catalog orders. The sandbox enforces the same tax declaration as production, so an integration cannot pass here and fail after go-live. Every API catalog order must state integrationOrderContext.salesCountryCode, integrationOrderContext.salesPriceGrossMinor, integrationOrderContext.salesTaxRatePercent and integrationOrderContext.salesChannel. Refusal codes are per field: salesTaxRatePercent or salesPriceGrossMinor missing (including JSON null) → 422 TAX_DECLARATION_REQUIRED; salesCountryCode missing → 422 SALES_COUNTRY_REQUIRED (catalog price guard; unchanged); salesChannel missing → 422 SALES_CHANNEL_REQUIRED, and a channel your agreement does not permit → 422 SALES_CHANNEL_NOT_PERMITTED. Any missing required field is refused before a key is delivered, so nothing is consumed and the call can be retried. GET /whoami lists the fields at data.requiredDeclarations for every key, and the complete per-operation list for the calling key (including the production commercial evidence a production key also needs on committing operations) at data.requiredDeclarationsByOperation; sandbox responses repeat both under data.sandboxCatalog. The Content Owner's share is computed on the price net of the consumer VAT you declare, so a sale that does not state its tax cannot be settled; see Order context.
Sandbox already provides a ready path for the first hour:
- A shared sandbox catalog with sandbox API keys (create yours in Console).
- An active connection and BMA with shared SKUs and priced API allocations.
- One pending title offer (the title of
SANDBOX-NOSHARE-001), soGET /api/seller/v1/partners/{connectionId}/offersreturns an example offer instead of an empty list. - Deterministic magic SKUs (including negative paths) and available inventory pools.
- Rehearsal data for flows a Content Owner starts (promotions, allocation decisions, stock events, an access proposal) and the controls that act as the vendor; see Sandbox mode → Rehearsing vendor actions.
- Support for a fake buyer checkout context:
salesCountryCode, retail currency, gross/net/tax minors, PSP reference, checkout session id, and payment method family. - Per-key webhooks capable of receiving
test.ping,order.fulfilled,order.reserved,order.keys_returned, and related events you subscribe to.
Magic SKUs, magic payment references, and bypass fixtures are sandbox-only. Production requests containing test namespaces or magic values are rejected server-side rather than silently mapped to real inventory.
Public documentation site#
Error hints may reference https://docs.avrix.io/seller-api/.... Interactive OpenAPI docs are
at /api/seller/v1/docs on https://api.avrix.io.
Related#
- Quickstart — sandbox-first golden path (~15 minutes)
- Scope matrix — scopes paired with sandbox keys
- IP allowlist — egress restrictions, and which keys need them
- Monitoring and support
- Error playbook — auth, scope, and environment error codes