Testing

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

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

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

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"

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

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.

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, idempotency_in_flight) that return the live codes without pulling keys

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=.
• 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.
• Simulate headers (sandbox only) — the modes in Sandbox return the live codes and pull nothing. Retry the same key without the header.

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:

# 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), SANDBOX-TERR-BLOCK-001 (US → territory rejection), and SANDBOX-PREORDER-001 (PRODUCT_NOT_SELLABLE) are asserted as contract codes. 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.

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.

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

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

• Certification — required evidence before go-live
• Troubleshooting — symptom-first triage
• Error reference — codes and recovery