Single checklist for integrators and solutions engineers. Authoritative semantics remain in the linked docs.
Environments#
| Environment | Base URL | Notes |
|---|---|---|
| Sandbox & production | https://api.avrix.io for GET /api/seller/v1/... · console at https://app.avrix.io | Same 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.requiredScopeson contract date2026-12-01and later, FORBIDDEN withdetails.missingScopeon 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;
coveragesays which were found. See Monitoring and support. - Idempotency —
Idempotency-Keyon 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.
integrationOrderContextRedactedmay appear onorder.fulfilled/order.reservedwhen 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 storedintegrationOrderContextfor reconciliation. Default integration keys may omit finance scope — enable in Settings → Integrations → API Keys.
Support checklist#
- Request id from client/logs.
- Idempotency key and whether the body changed between retries.
- Environment (sandbox vs production key) and whether integration-context strict mode applies.
- For webhook delays: enqueue time vs first HTTP attempt and delivery history.
- Escalate via support@avrix.io or your partner contact — full playbook in Monitoring and support.
Related#
- Quickstart
- Monitoring and support
- Error playbook
- Webhooks
- Sandbox — one-host model and support correlation
- Scope matrix — finance and operational scopes
- Integration recipes