Sandbox

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.

curl -s -X GET "https://api.avrix.io/api/seller/v1/whoami" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Integrators use a single public Seller API host. The API key environment (sandbox vs production) selects behaviour — not a separate hostname.

All Seller API routes are rooted at /api/seller/v1/ (versioned); unversioned paths redirect there. Health check: GET /api/seller/v1/health.

Sandbox lets you exercise deterministic catalog SKUs and fulfillment paths without touching your live inventory. Sandbox is enabled per deployment; GET /api/seller/v1/whoami returns a sandboxCatalog block when it is available to your key.

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 shared sandbox catalog with deterministic magic SKUs — your real company inventory is never touched.

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

All sandbox keys route to the same shared sandbox catalog, allocations, and key pools:

Magic SKUs (sandbox catalog only)

Sandbox keys also accept two TEST-NET consumer IPs (listed on GET /whoami → sandboxCatalog.magicConsumerIps) so you can exercise geo failures without production geo data. Production keys still reject these as reserved (CONSUMER_IP_INVALID).

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.

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

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.

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:

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)

Write-path modes (rate_limit on checkout, hot_path_timeout, key_decrypt_failed, billing_record_failed, internal_error, idempotency_in_flight) apply to POST /orders, POST /orders/bulk, POST /orders/commit, and POST /keys/pull. They fail before inventory work — retry the same Idempotency-Key without the header. rate_limit also applies to other sandbox routes.

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.

See Integration recipes for how to send integrationOrderContext on store orders.

1. Confirm sandbox is enabled — GET /api/seller/v1/whoami returns sandboxCatalog with tenantReady: true.
2. In the console: Settings → Integrations → API Keys → Create key → Environment: Sandbox.
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.

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:

   HTTPCopy

   Authorization: Bearer <your_seller_api_key>
   

Keys with null or empty scopes receive 403 INSUFFICIENT_SCOPE — they are not full access. Always create keys with the scopes you need.

Do not treat a 401/403 as “success” or mock a JSON body to continue development — fix auth, scopes, or network first.

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

If browser CORS origins are configured on the deployment, browser clients receive CORS headers. Server-to-server (Postman, curl, backend) does not require CORS.

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.

CURRENCY_NOT_PRICED_FOR_COUNTRY, SRP_MISMATCH_FOR_CURRENCY and CONSUMER_GEO_MISMATCH_POLICY_REFUSED cannot be triggered here. All three need contract values the sandbox does not use: the first two need an agreement permitting more than each country's own currency, and the third 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.

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; sandbox responses also repeat them under data.sandboxCatalog.requiredDeclarations. 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 INTEGRATION_ORDER_CONTEXT.md.

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.
• Deterministic magic SKUs (including negative paths) and available inventory pools.
• 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.

Error hints may reference https://docs.avrix.io/seller-api/.... Interactive OpenAPI docs are at /api/seller/v1/docs on https://api.avrix.io.

• Quickstart — sandbox-first golden path (~15 minutes)
• Scope matrix — scopes paired with sandbox keys
• IP allowlist — optional egress restrictions
• Monitoring and support
• Error playbook — auth, scope, and environment error codes