Partner runbook

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

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.

• Header: Authorization: Bearer <api_key>
• TLS: HTTPS only.
• Scopes: Keys may be scope-limited (seller:keys:pull, seller:finance:read, …). Missing scope returns 403 with details.missingScope / details.requiredScopes when applicable.
• Console path: Settings → Integrations → API Keys.
• Lifecycle (expiry, rotation, ~60s revocation): Authentication.

• X-Request-Id — Echoed on responses; use for support tickets and log correlation.
• Request inspector — GET /api/seller/v1/requests/{requestId} returns your own redacted trace from the audit log: endpoint, status, timing, API key id, allocation/SKU/key-pull correlation, and integration-context byte count. It never returns raw keys, webhook secrets, PSP tokens, or free-form metadata.
• Idempotency — Idempotency-Key on mutating requests; 24h replay window; body must match canonical JSON (409 on mismatch). See Integration recipes.

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

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

• Production keys are not rate limited (your IP allowlist is the gate). Sandbox keys share a flat abuse cap; response headers carry X-RateLimit-* metadata.
• 429 — Back off with jitter; do not spin tight retry loops.

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

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.

• Quickstart
• Monitoring and support
• Error playbook
• Webhooks
• Sandbox — one-host model and support correlation
• Scope matrix — finance and operational scopes
• Integration recipes