Partner runbook

Sandbox vs production, strict mode, and operational checks.

TopicsOperate

Single checklist for integrators and solutions engineers. Authoritative semantics remain in the linked docs.

Environments#

EnvironmentBase URLNotes
Sandbox & productionhttps://api.avrix.io for GET /api/seller/v1/... · console at https://app.avrix.ioSame host. Use a sandbox or production API key — the key selects the environment.

Canonical Seller API routes live under /api/seller/v1/.... Interactive docs: /api/seller/v1/docs, OpenAPI JSON: /api/seller/v1/openapi.

See Sandbox and Environments for key environment behaviour.

Authentication#

  • Header: Authorization: Bearer <api_key>
  • TLS: HTTPS only.
  • Scopes: Keys hold exactly the scopes granted at creation. Which scope each operation accepts is in the scope matrix. A missing scope returns 403: INSUFFICIENT_SCOPE with details.requiredScopes on contract date 2026-12-01 and later, FORBIDDEN with details.missingScope on earlier dates (error playbook).
  • Console path: Settings → Integrations → API Keys.
  • Lifecycle (expiry, rotation, ~60s revocation): Authentication.

Request correlation#

  • X-Request-Id — Echoed on responses; use for support tickets and log correlation.
  • Request inspector — GET /api/seller/v1/requests/{requestId} returns the call-log row for any request made with one of your keys (method, endpoint, status, latency, error code, API key id) and, where one was kept, a redacted trace with order, allocation/SKU and key-pull correlation. It never returns raw keys, webhook secrets, PSP tokens, or free-form metadata. Both records are kept for 90 days; coverage says which were found. See Monitoring and support.
  • Idempotency — Idempotency-Key on mutating requests; 24h replay window; body must match canonical JSON (409 on mismatch). See Integration recipes.

Declared retail (integrationOrderContext)#

  • Optional on orders, bulk lines, keys pull/export unless your key or environment requires it.
  • Production keys (default): require net/tax/PSP/checkout fields for commercial commits — see Integration recipes.
  • Per-API-key policy: a key can require additional field paths. GET /api/seller/v1/whoami reports the effective requirement for the calling key — check it before go-live rather than assuming the default.

Webhooks#

  • Register with POST /api/seller/v1/webhooks (seller:webhooks:write).
  • Verify X-Avrix-Signature (HMAC) before trusting the body.
  • Treat deliveries as at-least-once; dedupe by eventId / delivery id.
  • Latency: First attempt is often soon after enqueue with a short-cadence backstop; measure p50/p95 in your environment before promising sub-minute SLOs. See Webhooks.
  • integrationOrderContextRedacted may appear on order.fulfilled / order.reserved when context was sent (redacted subset only).

Rate limits#

  • Production keys have generous per-key fair-use limits (Rate limits); sandbox keys share a flat abuse cap. Response headers carry X-RateLimit-* either way.
  • 429 — Back off with jitter; do not spin tight retry loops.

Finance reads#

  • GET /api/seller/v1/finance/api-sales (requires seller:finance:read) returns rows with stored integrationOrderContext for reconciliation. Default integration keys may omit finance scope — enable in Settings → Integrations → API Keys.

Support checklist#

  1. Request id from client/logs.
  2. Idempotency key and whether the body changed between retries.
  3. Environment (sandbox vs production key) and whether integration-context strict mode applies.
  4. For webhook delays: enqueue time vs first HTTP attempt and delivery history.
  5. Escalate via support@avrix.io or your partner contact — full playbook in Monitoring and support.

What links here

Published guides that link to this page.

Search docs

Search documentation…