Sandbox

Test environments, magic SKUs, and auth triage.

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.

DimensionSandbox keyProduction key
Base URLhttps://api.avrix.iohttps://api.avrix.io
Consolehttps://app.avrix.iohttps://app.avrix.io
CatalogFixture catalog with magic SKUs (shared, or your store's isolated environment)Your real agreements and allocations
Key materialTest keysReal keys
Commercial evidenceThe 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)#

RuleDetail
Key determines environmentA sandbox key never acts as production inventory; a production key never accepts magic SKUs.
Same hostCall 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.
SupportWhen 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#

SymptomLikely causeFix
401 Invalid API keyWrong secret, revoked/rotated key, or typoRecreate / re-copy from Settings → Integrations → API Keys
401 API key expiredThe 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_MISMATCHA production key sent with X-Avrix-Sandbox: true, or a sandbox key used on a deployment where the sandbox is disabledDrop the header from production calls; use a production key on that deployment. GET /whoami shows data.key.environment and requestEnvironment
403 IP_NOT_ALLOWEDEgress IP not on the key allowed_ips listAdd your IP/CIDR in Settings → Integrations → API Keys, or test from an allowed network
Key works from your laptop but not from your serverAllowlist and/or wrong secret in that environmentRun 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:

  1. Create a Sandbox key in Settings → Integrations → API Keys (environment toggle).
  2. Call https://api.avrix.io with the sandbox key — X-Avrix-Sandbox: true is optional when sandbox is enabled (header still supported for explicit debugging).
  3. 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.

ConcernBehaviorMitigation
Key pool contentionHeavy parallel testing on SANDBOX-STD-001 can exhaust the finite pool → 409 NO_AVAILABLE_KEYS until pools are replenishedDefault to SANDBOX-ALWAYS-001 for CI, Postman, and load tests
Order isolationGET /orders is scoped per API key — integrators cannot read another sandbox key's orders by referenceUse unique orderReference values
Catalog visibilityAll integrators see identical products, availability, and allocation countsExpected for the shared sandbox catalog; webhooks remain per-key
Shared settingsPUT /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 runRehearse 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-001 and the other finite fixtures behave the same on every run. SANDBOX-LOWSTOCK-001 is still pinned at 3 keys and SANDBOX-NOKEYS-001 is still empty.
  • Public fixture codes do not change. You keep sending SANDBOX-ALWAYS-001, SANDBOX-STD-001 and 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.* and contract.* 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-Key and 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 by orderReference, 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 codeScenario
SANDBOX-STD-001Standard happy-path fulfillment
SANDBOX-ALWAYS-001Large 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-001409 NO_AVAILABLE_KEYS
SANDBOX-TERR-BLOCK-001Territory blocked (price list DE-only; use US in tests)
SANDBOX-ACTIVATION-LOCK-001Activation locked to Germany (keys only activate in DE; preview, hold and commit with US refuse with ACTIVATION_REGION_MISMATCH)
SANDBOX-BACKORDER-001Never in stock (backorderOnUnavailable: true returns awaiting_stock; order.backorder_expired after 15 minutes)
SANDBOX-REPLACE-PENDING-001Key replacements wait for the Content Owner (POST /orders/{orderId}/keys/{keyId}/replace answers 202 pending); approved a moment later, then key.replaced
SANDBOX-REVOKE-001Keys are revoked right after delivery (reason leaked); keys.revoked arrives with recommendedAction: replace
SANDBOX-PRICE-MIS-001Catalog price $59.99 — wrong expectedUnitPriceCents → mismatch
SANDBOX-NOALLOC-001Share without allocation → sellable: false, readiness NO_ALLOCATION
SANDBOX-NOSHARE-001No seller share — not in partner catalog; order by skuCode fails entitlement
SANDBOX-LIFECYCLE-001Shared/allocated but product not live → PRODUCT_NOT_SELLABLE
SANDBOX-LOWSTOCK-001Pool pinned at 3 keys — test partial availability and bulk strict semantics; quantity above stock → 409 NO_AVAILABLE_KEYS
SANDBOX-PREORDER-001Pre-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-001Wholesale-model allocation priced 2500 — any other expectedUnitPriceCents → WHOLESALE_PRICE_MISMATCH
SANDBOX-CHURN-001Rotates live ↔ delisted every 6 hours — poll GET /catalog/changes for added / removed tombstones
SANDBOX-PROMO-001Carries 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-001Refund window of 0 days: POST /refunds for a key sold on it answers 422 REFUND_WINDOW_EXPIRED
SANDBOX-REDEEMED-001Keys are marked redeemed right after delivery: POST /refunds or POST /keys/return for them answers 409 KEY_NOT_RETURNABLE
SANDBOX-ALLOC-REQUEST-001An 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 IPExpected outcome on preview / reserve / hold / commit
203.0.113.66422 CONSUMER_GEO_MISMATCH
203.0.113.99422 CONSUMER_IP_HIGH_RISK
203.0.113.77422 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 typeExample prefix
Live (production)avrix_sk_live_…
Sandboxavrix_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 availabilityX-Avrix-Sandbox: true?Allowed key environment(s)
Sandbox enablednosandbox keys allowed without header
Sandbox disablednoproduction only
Sandbox enabledyessandbox 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 /orders to 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 emit allocation.updated (reasons pulled / returned), and share-scope changes emit sku.sellability_changed, so a store can exercise both handlers in sandbox.

Simulate headers (sandbox only)

HeaderEffect
X-Avrix-Sandbox-Simulate: rate_limitReturns 429 RATE_LIMIT_EXCEEDED (Retry-After: 2)
X-Avrix-Sandbox-Simulate: hot_path_timeoutReturns 504 HOT_PATH_TIMEOUT (Retry-After: 1); nothing pulled
X-Avrix-Sandbox-Simulate: key_decrypt_failedReturns 503 KEY_DECRYPT_FAILED (Retry-After: 5); nothing pulled
X-Avrix-Sandbox-Simulate: billing_record_failedReturns 503 BILLING_RECORD_FAILED (Retry-After: 5); nothing pulled
X-Avrix-Sandbox-Simulate: internal_errorReturns 500 INTERNAL_ERROR
X-Avrix-Sandbox-Simulate: service_unavailableReturns 503 SERVICE_UNAVAILABLE (Retry-After: 5); nothing pulled — rehearse a database or dependency outage
X-Avrix-Sandbox-Simulate: idempotency_in_flightReturns 409 IDEMPOTENCY_REQUEST_IN_FLIGHT (Retry-After: 5)
X-Avrix-Sandbox-Simulate: webhook_delay_30sDelays the first webhook delivery attempt by 30 seconds
X-Avrix-Sandbox-Simulate: buyer_verification_requiredCheckout 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/commit and POST /keys/pull honour 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 same Idempotency-Key without the header.
  • Every other write (refunds, returns, cancellations, holds, reservations, allocation and webhook changes, and the rest) honours rate_limit, internal_error and service_unavailable, answered before any work. This includes POST /orders/cancel, POST /orders/recover-keys, POST /keys/export, POST /keys/return, POST /refunds and POST /chargebacks/resolve, which ignored the header before, so you can rehearse the retry logic of every write.
  • Reads honour rate_limit.
  • buyer_verification_required is honoured by POST /orders, POST /orders/bulk, POST /orders/commit, POST /keys/pull, POST /orders/hold, POST /orders/preview and POST /orders/reserve. Rehearse the whole path: mint an attestation with POST /geo/attest, have the buyer's browser complete it, read its state with GET /geo/attest/{attestId}, and resend the order with the attestId. 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-SimulateRouteFirst attemptRetry with the same key and body
timeout_then_successPOST /orders504 HOT_PATH_TIMEOUT (Retry-After: 1) before anything is committedPlaced once, normally
error_after_commitPOST /ordersThe order is committed and its idempotent result stored, then the response is replaced by 500 INTERNAL_ERRORReplays the original order (Idempotency-Replayed: true); no second pull
webhook_delay_duplicatePOST /ordersSucceeds; order.fulfilled is delivered 30 seconds late and twice with the same eventIdReplays normally
partial_cartPOST /orders/bulkThe 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 outcomesReplays normally
sold_out_after_holdPOST /orders/holdThe hold succeeds and the response describes it; right after, the hold is released and your environment's remaining stock of that SKU is blockedCommitting 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 new Idempotency-Key starts 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_hold is then given back to your pool.
  • Fault responses carry details.simulate with the scenario name. No scenario changes another store's environment or any production data.
  • On the shared sandbox catalog, and for partial_cart or sold_out_after_hold on POST /orders, the request answers 422 SANDBOX_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}/accept or /decline).
  • A closed refund window on SANDBOX-REFUND-EXPIRED-001 and keys redeemed after sale on SANDBOX-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/proposals lists 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.

ControlWhat it doesShared sandbox
POST /sandbox/allocations/requests/{requestId}/resolveThe 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-eventsSends allocation.low_stock or allocation.depleted for one of your allocations without selling anything.Yes
POST /sandbox/promotions/deals/{responseId}/windowMoves a deal the vendor sent so it starts now or ends now; an approved deal sends promotion.started or promotion.ended.No
POST /sandbox/resetPuts 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 onlyOptional
schemaVersion, salesCountryCode, salesPriceGrossMinor, salesTaxRatePercent, salesChannelcurrencyCode, salesPriceNetMinor, priceIncludesTax, salesTaxAmountMinor, paymentMethodFamily, paymentProcessorReference, checkoutSessionId, consumerIpEvery 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)#

  1. In the console: Settings → Integrations → API Keys → Create key → Environment: Sandbox.
  2. Confirm the sandbox is ready for that key — GET /api/seller/v1/whoami returns sandboxCatalog with tenantReady: true.
  3. Call https://api.avrix.io with Authorization: Bearer <sandbox_key> (optionally X-Avrix-Sandbox: true).
  4. 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#

  1. In the Avrix console, open Settings → Integrations → API Keys (seller company).

  2. Create a key and assign scopes for the recipes you need (see Scope matrix).

  3. Send every request with:

    HTTP
    Authorization: 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#

SymptomLikely causeWhat to do
403 with message about missing scopeKey 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.
401Missing/invalid Authorization, wrong key format, expired, or revoked key.Verify Bearer prefix, no extra quotes, key environment. See Error playbook.
403 from IP allowlistKey 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-Id when the API sends standard headers. Always log it when reporting issues.
  • Error bodies may include requestId, code, hint, and doc_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 seeSend
SALES_CHANNEL_REQUIREDAn order with no integrationOrderContext.salesChannel.
SALES_CHANNEL_NOT_PERMITTEDsalesChannel: "marketplace:steam". Any marketplace:<slug> is outside own_storefront.
FOOTPRINT_COUNTRY_NOT_DECLAREDsalesCountryCode: "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_TERMA 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), so GET /api/seller/v1/partners/{connectionId}/offers returns 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.

What links here

Published guides that link to this page.

Search docs

Search documentation…