Testing

Sandbox magic SKUs, mocks, contract tests, and webhook verification.

TopicsGo live

How to exercise the Seller API safely before production: sandbox magic SKUs, mocks, contract tests, and webhook replay.

What this covers#

Sandbox fixtures, what to assert in CI, and how to verify webhooks without guessing signatures. Start from Sandbox if you still need a key.

Prerequisites#

  • Sandbox API key (environment = sandbox)
  • Ability to receive HTTPS webhooks (public HTTPS endpoint or temporary tunnel)
  • Stable Idempotency-Key values in automated suites

Confirm the key#

Call GET /whoami first. Assert environment, scopes, and capabilities before any order test.

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

Sandbox magic SKUs#

The shared sandbox catalog includes deterministic SKUs for happy and negative paths:

SKUUse for
SANDBOX-ALWAYS-001Happy path preview → order → fulfilment (large replenished pool)
SANDBOX-STD-001Standard happy-path fulfilment (finite pool — prefer ALWAYS for CI)
SANDBOX-EUR1-001Cheap PSP dogfood (~€1); countryCode DE/FR/NL, expectedUnitPriceCents 100
SANDBOX-NOKEYS-001Out of stock — preview canFulfill: false, order 409 NO_AVAILABLE_KEYS
SANDBOX-TERR-BLOCK-001Territory block (DE-only price list; use countryCode US)
SANDBOX-PRICE-MIS-001Wrong expectedUnitPriceCents → 422 CATALOG_PRICE_MISMATCH
SANDBOX-WHOLESALE-MIS-001Wholesale grant at 2500¢ — any other bind → WHOLESALE_PRICE_MISMATCH
SANDBOX-NOALLOC-001Share without allocation — sellable: false, order fails entitlement
SANDBOX-NOSHARE-001No seller share — not in partner catalog
SANDBOX-LIFECYCLE-001Product not live → PRODUCT_NOT_SELLABLE
SANDBOX-PREORDER-001Pre-order window open: preview fulfillmentType: "pre-order"; POST /orders → awaiting_release, no keys
SANDBOX-LOWSTOCK-001Pool pinned at 3 keys — qty 1 succeeds, qty 4 → 409
SANDBOX-KEYLESS-001Hosted redemption when whoami.capabilities.keylessEnabled is on
SANDBOX-CHURN-001Live ↔ archived every 6 hours — poll GET /catalog/changes

Prefer SANDBOX-ALWAYS-001 for golden-path CI. For live PSP test charges, prefer SANDBOX-EUR1-001 so the catalog/bind price is €1.00 — still use your processor’s test mode; do not charge production cards against sandbox orders.

Production store scenarios#

A store-scenario matrix walks every integration profile and magic SKU against Production (https://api.avrix.io) with a sandbox key. It covers:

  • Profile A — GET /whoami, GET /partners, GET /integration/status, catalog browse, GET /products/{id} for SANDBOX-ALWAYS-001, allocations (sellable: true), preview gate, POST /orders, idempotent replay, orderReference replay
  • Profile B — sellable catalog sync, availability, reconcile (GET /orders?orderReference=, transactions, events), finance ledger (GET /finance/api-sales, GET /finance/summary), webhook test ping plus HMAC fixture verify, optional checkout hold, one refund plus GET /refunds, and POST /keys/return
  • Profile C — hot-drop reserve/commit, or 412 HOT_DROP_NOT_ENABLED as a valid fallback to Profile B
  • Magic SKU gates — the table above, including extra-platform browse (SANDBOX-ALWAYS-PS5-001)
  • Multi-SKU cart — POST /orders/bulk with strict: true (happy path and a failing line that returns 422 VALIDATION_FAILED with no ALWAYS fulfillment)
  • Recoveries — 409 after a simulated PSP charge (refund guidance) and same orderReference + higher quantity → 409 ORDER_REFERENCE_CONFLICT (never top up)
  • Live-key isolation — a production-environment key must not see or pull sandbox magic SKUs
  • Exceptional paths — auth and the error envelope, catalog freshness (If-None-Match 304, checksum, since=), missing Idempotency-Key, price/country/currency validation, unknown-outcome replay, hold and hot-drop faults, refund lookup and compensated replay after a full refund, bulk contract-date defaults, webhook signature rejects, and sandbox simulate headers (rate_limit, hot_path_timeout, key_decrypt_failed, billing_record_failed, internal_error, service_unavailable, idempotency_in_flight) that return the live codes without pulling keys

Exceptional store paths#

A store must handle more than the happy path. Against sandbox, rehearse:

  • Auth and envelope — missing or garbage Bearer (UNAUTHORIZED), KEY_ENVIRONMENT_MISMATCH, UNSUPPORTED_API_VERSION, missing Idempotency-Key (BAD_REQUEST). Every error includes code, requestId, recoverable, and doc_url.
  • Validation — SALES_COUNTRY_REQUIRED, EXPECTED_UNIT_PRICE_REQUIRED, CURRENCY_MISMATCH, quantity: 0, empty or unknown skuCode.
  • Catalog freshness — If-None-Match 304, GET /catalog/checksum, GET /catalog/changes?since=.
  • Idempotency — same key + different body → IDEMPOTENCY_KEY_MISMATCH; same orderReference + higher quantity → ORDER_REFERENCE_CONFLICT before you refund. After a full refund the same reference may pull again (compensated replay).
  • Unknown outcome — abort the HTTP call, then replay the same Idempotency-Key and look up GET /orders?orderReference=. In your store's isolated sandbox environment, X-Avrix-Sandbox-Simulate: error_after_commit commits the order and answers 500 once; the retry with the same key and body must recover it (see Stateful fault scenarios in Sandbox).
  • Hold / hot-drop — HOLD_NOT_FOUND, HOLD_MISMATCH, CHECKOUT_HOLD_DISABLED, HOT_DROP_NOT_ENABLED, RESERVATION_GONE.
  • Refunds — GET /refunds/{refundId}, unknown keyIds, no plaintext on GET /orders.
  • Bulk contract dates — omit strict and pin X-Avrix-Api-Version: 2026-09-01 (whole cart) vs 2026-04-29 (partial).
  • Webhooks — reject stale and missing signatures; reject non-HTTPS and loopback URLs. With a sandbox key, POST /webhooks/{id}/test sends any event type and the invalid_signature, stale_timestamp, duplicate and previous_secret_only receiver challenges (see Webhooks).
  • Simulate headers (sandbox only) — the modes in Sandbox return the live codes and pull nothing. Retry the same key without the header.

Ops and recovery#

After the first charge, rehearse the store-ops paths — not more commerce gates.

  • Webhook consumer — dedupe on X-Avrix-Event-Id (same signed body twice is still 200). After PATCH /webhooks/{id} with rotateSecret: true, accept both the new secret and the previous one during the overlap window. GET /webhooks and GET /webhooks/{id}/deliveries after /test are the ops reads.
  • Delayed delivery — X-Avrix-Sandbox-Simulate: webhook_delay_30s on POST /orders still returns 200 and the order is immediately visible on GET /orders?orderReference=. Buffer by orderReference until the signed event arrives; do not wait on the HTTP response to persist keys.
  • Ledger sweep — page GET /orders?from=&to=&cursor= (there is no updatedSince). The Profile A orderReference appears; responses never include plaintext keys.
  • Price bind — when preview returns priceCommitmentToken, echo it on POST /orders. A tampered token is 422 PRICE_COMMITMENT_INVALID. If preview omits the token, skip — the deployment is not issuing binds.
  • Hold / hot-drop depth — replay the same hold Idempotency-Key; commit after DELETE /orders/hold still fulfils and reports checkoutHold.committedWithoutHold: true. Conflicting expectedUnitPriceCents / expectedWholesaleUnitPriceCents is EXPECTED_PRICE_CONFLICT (or VALIDATION_FAILED). One successful POST /orders/{reservationId}/extend, then RESERVATION_EXTEND_EXHAUSTED. Concurrent commits yield one fulfilment or RESERVATION_COMMIT_IN_PROGRESS. Simulate hot_path_timeout on commit (not only POST /orders) — nothing fulfilled.
  • Price drift — after CATALOG_PRICE_MISMATCH, re-preview and submit the new cents. Do not retry the old price.

From the Avrix repository, with AVRIX_API_KEY set to a sandbox key:

Bash
# Production (sandbox key required; mutation-capped)
AVRIX_API_KEY=avrix_sk_sbx_your_key_here \
  node scripts/run-seller-store-scenarios.mjs --base-url https://api.avrix.io --sandbox --no-seed

# Same matrix against a running local app
AVRIX_API_KEY=avrix_sk_sbx_your_key_here \
  node scripts/run-seller-store-scenarios.mjs --sandbox --no-seed

SANDBOX-EUR1-001 (DE preview/order at €1.00) and SANDBOX-TERR-BLOCK-001 (US → territory rejection) are asserted as contract codes, and SANDBOX-PREORDER-001 as an order accepted as awaiting_release (the run cancels it again). Production sandbox picks up those catalog pins on the next sandbox catalog refresh. The suite never seeds inventory, never load-tests Production, and refuses a production-environment key.

What to mock vs call live#

LayerRecommendation
Your storefront UIMock your own BFF; never call Avrix from the browser
Unit tests for mappersMock HTTP; assert request shape and error mapping
Contract / integrationHit sandbox with magic SKUs
Webhook handlersReplay signed fixtures; verify HMAC on raw body

Contract tests#

Minimum assertions against sandbox:

  1. GET /whoami — sandbox environment and required scopes.
  2. Catalog sync — snapshot + allocations merge yields sellable SKUs.
  3. POST /orders/preview — canFulfill true for SANDBOX-ALWAYS-001.
  4. POST /orders — same Idempotency-Key replays the same order.
  5. Webhook — signature verifies; handler is idempotent.

Webhook verification in tests#

Verify HMAC over the raw body before parsing JSON.

# Verification is server-side in your webhook handler — not a curl call.
# Header: X-Avrix-Signature: t=<unix>,v1=<hex>[,v1=<hex>] (two v1 during a secret rotation; accept either)
# Signed payload: "{t}.{rawBody}" with HMAC-SHA256 and your endpoint secret.

Replay recorded deliveries (or console “resend”) against your webhook endpoint. Handlers must tolerate duplicates — see Webhooks and Polling and reconciliation.

Common mistakes#

  • Asserting plaintext keys on GET /orders (they are never returned there).
  • Running production keys in CI “because sandbox was empty”.
  • Treating a single mocked 200 as coverage of 409 / territory failures.

Next steps#

What links here

Published guides that link to this page.

Search docs

Search documentation…