Sandbox to production

Everything that differs between the two environments, the test cases Avrix requires before granting production access, and the cutover procedure.

Read this before you finish building, not after. Production enforces requirements that sandbox does not, and discovering them at cutover means rework at the worst possible time.

Both use the same host. Your API key determines the environment, not the URL.

Every integrator's sandbox key routes to the same fixture catalog. You see the same products, allocations, and availability as everyone else.

Practical consequences: use unique orderReference values, since the namespace is shared; expect availability counts to move for reasons unrelated to your testing; and prefer SANDBOX-ALWAYS-001, whose pool is continuously replenished, over pools that can be exhausted by other integrators' load tests.

Your orders and webhooks remain isolated per API key. Nobody can read your orders.

The most common cause of a sandbox-passing integration failing in production.

Every order carries an integrationOrderContext describing the retail transaction. Sandbox accepts a minimal set so you can iterate quickly. Production enforces the full set.

The authoritative field matrix — including all eleven fields required on production keys — is in Order context. Treat that page as the contract; do not rely on a shortened summary here.

Implement the production set from day one, even in sandbox. Sending complete evidence in sandbox costs nothing and removes an entire class of cutover failure.

Headline production gotchas:

• paymentProcessorReference — Required on production keys. Use the real reference from your PSP; fixture values like sandbox_pay_* fail with SANDBOX_MAGIC_VALUE_REJECTED.
• consumerIp — Required on production keys. Behind a load balancer or CDN, the immediate peer address is your own infrastructure. You must extract the real client address from proxy headers. Private and reserved ranges are rejected (CONSUMER_IP_REQUIRED / CONSUMER_IP_INVALID).
• checkoutSessionId — Required on production keys (not optional / recommended).

Also: SANDBOX_MAGIC_VALUE_REJECTED. Any fixture value left in your code — a magic SKU, a sandbox_pay_* reference — fails on a production key. Audit for hardcoded test values before cutover.

Avrix requires evidence that your integration handles the failure paths, not just the happy path. Failure paths are where money is lost, and they are what production access is granted against.

The full 29-case suite, evidence format, and fixture mapping live in Certification — run that list in sandbox and keep requestIds. This page keeps only the cutover narrative below.

Before cutover, confirm especially: allocation merge into your sellable set, unknown-outcome replay with a stable Idempotency-Key, invalid webhook signature rejection, and post-charge NO_AVAILABLE_KEYS refund at your PSP.

• Production key created with least-privilege scopes — not a copy of your sandbox scope set
• Separate keys per service
• Secrets in a managed secret store, never in source control
• Rotation scheduled and the procedure rehearsed
• IP allowlist configured, verified with GET /whoami-ip from production infrastructure
• No key in client-side code, mobile apps, or logs

• All fixture values removed — no magic SKUs, no sandbox_* references
• Full commercial evidence set implemented, including consumerIp from real proxy headers
• Catalog sync includes the allocations merge
• All paths versioned /api/seller/v1/...
• Idempotency-Key on every write, stable per logical order
• expectedUnitPriceCents echoed from preview on every order
• Entitlements persisted before the buyer response
• Webhook signatures verified with the raw body and constant-time comparison

• Alerting on error rate by code
• Alerting on webhook delivery failure
• requestId captured in structured logs
• Reconciliation job scheduled
• Runbook written for: sold out after payment, unknown order outcome, webhook endpoint down, key rotation, price mismatch spike
• Escalation path documented, including who is on call

• BMA active with each vendor — confirm hasActiveBma on GET /whoami
• Allocations granted for every SKU you intend to sell
• Territory pricing confirmed for every market you sell into
• Buyer-facing refund policy published and consistent with your PSP setup
• Settlement and invoicing understood by your finance team

1. Request production access with your certification evidence.
2. Create the production key with least-privilege scopes. Do not reuse the sandbox key's scope set without review.
3. Configure the allowlist if you use one, verified from production infrastructure.
4. Register production webhooks. Sandbox endpoint registrations do not carry over. Store the new secret.
5. Cold-start the catalog against production. Your sandbox mirror is fixture data and must be discarded.
6. Verify with GET /whoami — environment must be production and hasActiveBma true.
7. Run one controlled live order. A single unit of a low-value SKU, ideally an internal purchase. Confirm the key delivers, the webhook arrives and verifies, and the order reconciles.
8. Enable buyer traffic gradually. A percentage rollout or a single market first, so a defect affects few buyers.
9. Watch for 24 hours — error rates by code, webhook delivery success, reconciliation drift.

If something is wrong after cutover:

Immediate. Disable the affected SKUs or halt checkout at your storefront. This stops new exposure without touching Avrix.

If credentials are implicated. Revoke the production key in the Console. All requests stop within about 60 seconds. Availability is recoverable; leaked inventory is not.

If the webhook endpoint is failing. Disable it in the Console rather than letting it fail repeatedly into auto-disable, fix it, then replay the missed deliveries.

What you cannot roll back. Fulfilled orders. Keys are drawn from real inventory and delivered. Use the refund and key return path — see Order lifecycle.

Reconcile before resuming: compare your order records against GET /orders for the affected window and resolve every discrepancy before taking new orders.

Monitor: error rate by code (a spike in CATALOG_PRICE_MISMATCH means stale catalog data), webhook delivery success, reconciliation drift, allocation depletion, and rate-limit headroom.

Maintain: rotate keys on schedule, keep catalog sync current, review new webhook events as they are introduced, and re-run the certification suite after significant changes to your checkout.

• Certification — required test cases and evidence format
• Authentication — keys, scopes, rotation
• Monitoring and support
• Order lifecycle — failure modes
• Webhook guide — verification and reconciliation
• Error reference — every code