Sandbox to production

Readiness checklist and cutover steps before your first live order.

TopicsGo live

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

Sandbox to production promotion#

Diagram

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.

The environments#

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

SandboxProduction
Base URLhttps://api.avrix.iohttps://api.avrix.io
Key environmentsandboxproduction
CatalogFixture catalog (shared, or your store's isolated sandbox environment)Your real agreements and allocations
VendorsFixture vendorYour actual vendor relationships
Key materialTest keys, no valueReal keys, real cost
Magic SKUsAcceptedRejected — SANDBOX_MAGIC_VALUE_REJECTED
Commercial evidenceMinimalFull set enforced
Consumer geo enforcementNever enabledEnabled where the deployment enables it
WebhooksIsolated per API keyPer registered endpoint
Financial impactNoneReal settlement obligations

Shared catalog, then your own environment#

Until Avrix moves your store to its isolated sandbox environment, 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.

Once your store runs in its isolated environment, its catalog, stock and fault scenarios are your store's alone, and the same public fixture codes keep working. Product, SKU and allocation ids change at that move: take a fresh catalog snapshot. Neither environment shares ids with production, so nothing you stored from sandbox carries over to your live catalog. See Isolated store environments in Sandbox.

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

Commercial evidence#

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

Every order carries an integrationOrderContext describing the retail transaction. Sandbox keys require the settlement declarations (sale country, gross price, tax rate, sales channel). Production keys also require the full commercial evidence. The one table of what each key must send is in Sandbox.

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.

Certification#

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 28-case suite, evidence format, and fixture mapping live in Certification — run that list in sandbox and keep requestIds. The automatic report (GET /sandbox/certification) shows which cases your sandbox traffic already proves. 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 readiness checklist#

Credentials#

  • 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
  • Production key pinned to the egress IPs GET /whoami-ip reports from production infrastructure, or to a trusted workload
  • No key in client-side code, mobile apps, or logs

Implementation#

  • 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

Operations#

  • 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

Commercial#

  • 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

Cutover#

  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. Pin the production key to your egress IPs, verified with GET /whoami-ip from production infrastructure, or bind it to a trusted workload. The Console requires one (IP allowlist).
  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 — data.key.environment must be production, productionAccess.status approved, hasActiveBma true, and warnings free of PRODUCTION_ALLOWLIST_MISSING.
  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.

Rollback#

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.

After launch#

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.

What links here

Published guides that link to this page.

Search docs

Search documentation…