What to watch in production, how to correlate failures, how to escalate, and what Avrix will (and will not) promise in public docs.
Support#
| Channel | Use |
|---|---|
| support@avrix.io | Production incidents, integration blockers, certification evidence hand-off |
| Your Avrix partner / pilot contact | Pilots and commercial onboarding — prefer this when you have a named contact |
Support is by email; there is no ticket portal. Avrix does not publish support hours, response times or a severity model. Where your commercial agreement sets them, those apply.
Never paste API key secrets, webhook signing secrets, or game-key plaintext into tickets. Include
requestId (see below).
Status and incidents#
The public status page at https://avrix.io/status shows each Seller API capability (order placement, catalog, webhooks, background jobs, sandbox), the recent history and every published incident. It reads the same signals as GET /api/seller/v1/health.
The status page has no subscription. To be told about planned changes, use the channels under API changes and deprecations; for an active incident, open support at support@avrix.io (the address the status page's "contact support" link also uses) with the correlation fields below.
Service levels#
Avrix publishes no service-level targets in these guides: no availability percentage, delivery latency or support response time is promised here. The only SLA that applies to you is the one in your commercial agreement; if it names none, there is none. What you can see for yourself is measured live:
| Signal | Where you can see it |
|---|---|
| Order placement availability | Status page, "Order placement"; components.orderPath |
| Webhook delivery latency, event created → delivered (p95 and p99, last hour) | components.webhookDelivery.deliveryP95Seconds / deliveryP99Seconds |
| API key revocation taking effect | Within about 60 seconds of revoking or rotating a key (Authentication) |
| Recovery after a failed checkout that already charged the buyer | Retry and recover keys first (Key recovery); refund only when no live keys exist |
Planned maintenance#
Planned maintenance is communicated via your partner contact and/or email when scheduled. When
Avrix announces it over the API, it arrives as a platform.notice webhook event with category
maintenance on every endpoint subscribed to that event.
Design clients for transient 5xx with exponential backoff and the same Idempotency-Key on
retries. See Idempotency and Error playbook.
API changes and deprecations#
Contract changes, new refusals, deprecations and the switch of rate limits from shadow mode to enforced are announced in the Changelog. Two channels bring them to you:
- the changelog's RSS feed,
https://docs.avrix.io/changelog.xml(one item per dated entry), in a feed reader or a channel integration your on-call team reads; - the
platform.noticewebhook event: add it to an endpoint'seventsand each announcement arrives as a signed delivery with a category, a date and a link to the details (see Event reference).
A deprecated operation or parameter with a scheduled date also answers with Deprecation and
Sunset headers; alert on them in your HTTP client. Scheduled removals and their sunset dates are
listed under Versioning and compatibility.
What to watch#
| Signal | Why |
|---|---|
| POST /orders success rate | Buyer-facing fulfilment health |
409 NO_AVAILABLE_KEYS after charge | Preview / hold / stock race — refund path must work |
402 / payment-related denials (if applicable to your flow) | Commercial or entitlement gate spike |
422 spikes (CATALOG_PRICE_MISMATCH, territory, evidence) | Catalog drift or missing production IOC fields |
429 rate | Sync too aggressive for the per-key limits (see Rate limits); ask Avrix about launch headroom |
| Idempotency mismatches / in-flight | Client retry bugs |
| Webhook delivery failure rate | Endpoint down, signature bugs, slow handlers |
| Pull velocity anomalies | Compromised key or runaway job |
| Reconciliation drift (GET /orders vs local OMS) | Missed webhooks or unknown-outcome gaps |
| Orphan PSP captures (no Avrix aggregate) | Unknown-outcome gap in checkout |
Alert on sustained error budgets, not single sandbox noise.
Recommended partner alerts#
Prioritise these in production:
- Webhook delivery failures — sustained non-2xx or auto-disable on your endpoint
402/409rate — especially NO_AVAILABLE_KEYS after a successful PSP charge- Reconciliation drift — local paid orders missing from GET /orders (or the reverse)
429spikes — rate-limit bursts that indicate a runaway sync or missing ETag / backoff
Server-Timing on availability#
GET /availability and GET /availability/{skuCode} return a Server-Timing header on every
200 (also exposed to browsers via Access-Control-Expose-Headers): db;dur=… (grant, readiness
and inventory reads), redis;dur=… (the checkout-hold ledger), sellability;dur=… (the
per-country answer when country= was sent) and total;dur=…, in milliseconds. A slow
response therefore says where the time went — a cold function shows as a large total with
small phases, a slow query as a large db. Requests above the platform threshold (1 s by
default) also emit one structured log line tagged seller-api-timing with the same phases, which
support correlates by X-Request-Id. Send X-Request-Id when you report a tail.
Server-Timing on preview and orders#
POST /orders/preview and POST /orders return a Server-Timing header on every 200, one entry
per phase that ran, in milliseconds: auth, idempotency, sku-resolve, allocation,
availability, authority, term, geo, price, settlement, rpc (the key pull itself),
decrypt, billing (the sale record), idempotency-commit, then total. The names are stable.
Most of an order's time is the sequence of platform reads around a short pull; this header shows
which one a slow response spent its time in. Requests above the platform threshold also emit the
seller-api-timing log line with the same phases.
Request correlation#
Every response carries an X-Request-Id header, and every error body repeats it as requestId.
Send your own id in X-Request-Id to tie a call to your logs: 8 to 128 characters from A-Z,
a-z, 0-9, _, ., : and - (a UUID or ULID fits), a new value for every attempt. On
contract date 2026-12-01 and later a value outside that format is refused with
400 INVALID_REQUEST_ID; earlier dates echo any value. Omit the header and a UUID is generated.
When opening a ticket, include:
| Field | Example |
|---|---|
requestId / X-Request-Id | req_01J8XYZ... |
orderReference | store-order-10432 |
| Approximate UTC timestamp | 2026-08-05T09:14:22Z |
| Environment | sandbox / production |
| API key id (not the secret) | From Console → Settings → Integrations → API Keys |
Route + HTTP status + error code | POST /orders → 409 NO_AVAILABLE_KEYS |
Looking a request up#
GET /api/seller/v1/requests/{requestId} answers from two records, both kept for 90 days:
| Record | What it holds | Which requests |
|---|---|---|
callLog | Method, endpoint, status, latency, error code and key id | Every response to a request made with one of your keys, looked up in the calling key's environment. Not a 401 (the key was not identified). |
traces | The fields an order or refund needs: orderReference, outcome (fulfilled, preordered, backordered, deferred, replayed, reserved, refunded, returned), keyPullId, pulledCount | Sampled; see below |
coverage says what was found: detailed (a trace), summary (a call-log row only) or none.
webhookDeliveries lists the deliveries the request produced (sameRequest: true) and later
deliveries for the same order reference, such as a preorder fulfilled afterwards, with their
status, attempts and lastError. Only your own endpoints are listed and payloads are not
included, so "did we send order.fulfilled for this order?" is answered from one call. Raw keys
are never returned.
An id nothing recorded answers 404 NOT_FOUND on contract date 2026-12-01 and later, with
details.lookupRequestId and details.retentionDays. Earlier dates answer 200 with
coverage: "none" and empty lists. Check the id you logged and the key's environment (a
production key does not see sandbox requests).
Which requests get a trace:
| Request | Trace kept |
|---|---|
A write (POST, PATCH, PUT, DELETE) on the order, key pull, key export, key return, refund or webhook routes | Always. A successful POST /orders/preview counts as a read. |
| An error response the route records on those same routes | Always |
A 429, or a 5xx the route records, on any other route | Always |
Another 4xx response on any other route | About 1 in 10 |
A successful response (2xx, 3xx) on any other route, and a successful read on the routes in the first row | About 1 in 100 |
A request refused before its handler ran: 401, a missing scope, an address outside the IP allowlist. Also some validation refusals and unexpected failures that a route answers without recording. | Never |
The two sampled rates are the current ones and can change. When you open a ticket, send the
requestId either way.
Keep requestId in your structured logs for every Seller API call and every webhook handler
invocation you correlate to an Avrix delivery. Retention of those log lines is your policy; Avrix
keeps commercial evidence and delivery history under the schedules in
Data handling and your DPA — not as a substitute for your own logs.
Escalation path#
- Self-serve — check
GET /whoami, deliveries list,GET /orders?orderReference=, catalog changes. - Replay — webhook delivery replay for missed push events (metadata only).
- Support — email support@avrix.io (or your partner contact) with the correlation table above.
- Security incident — revoke keys first (Security / Authentication), then escalate.
Compliance and transport#
- TLS: Seller API traffic is HTTPS only. Do not send credentials over cleartext.
- Data roles and retention: Data handling.
- Compliance package (SOC reports, questionnaires, etc.): ask Avrix for the current package under your commercial / DPA process — do not assume a specific certification from public docs alone.
Health and introspection endpoints#
| Check | Route |
|---|---|
| Platform up | GET /api/seller/v1/health (no auth) |
| Key / company / capabilities | GET /api/seller/v1/whoami |
| Can the company sell yet | GET /api/seller/v1/integration/status |
| Egress IP discovery | GET /api/seller/v1/whoami-ip |
| Usage summary | GET /api/seller/v1/usage |
| Activity feed | GET /api/seller/v1/activity |
| Redacted request trace | GET /api/seller/v1/requests/{requestId} |
Which call answers what#
GET /whoami describes the key; GET /integration/status describes the company's progress
to selling. Ask each only its own question.
| Question | Call | Read |
|---|---|---|
| Which company, key and environment is this, and what may it do? | GET /whoami (any seller scope) | company, data.key.environment, data.key.scopes, capabilities, warnings |
| What does each order call refuse without, for this key? | GET /whoami | requiredDeclarationsByOperation |
| Can we sell yet, and if not, what is missing? | GET /integration/status (seller:products:read) | readyToSell, and each of gates[] with satisfied and hint |
readyToSell is true once the commerce-critical gates pass: bmaActive, shareGranted,
allocationGranted and territoryPricingSet. The other gates (webhookConfigured,
testPingSucceeded, firstOrderCompleted) track the rest of onboarding and do not hold it back.
whoami.integrationReadiness carries the SKU counts and blockers behind those gates; it has no
readyToSell and does not check webhooks or orders, so use GET /integration/status for the
answer and integrationReadiness only for the counts.
What GET /health reports#
The top-level status is degraded when the database probe fails (HTTP 503) or when one of the
delivery queues is degraded (HTTP 200, with degradedReasons naming each cause). Queue components:
| Component | Field | Meaning | Degraded when |
|---|---|---|---|
webhookDelivery | pending | Deliveries still to send; leaves out deliveries buffered for a disabled endpoint | more than 5,000 pending |
webhookDelivery | buffered | Deliveries held for disabled endpoints until they are re-enabled (see Webhooks) | informational |
webhookDelivery | dueLagSeconds | How long the oldest delivery that is already due has waited past its due time | more than 900 seconds |
webhookDelivery | failedLast24h | Deliveries that exhausted their retries in the last day | informational |
outboxJobs | pending | Background jobs (catalog exports, settlement follow-ups) still to run | more than 500 pending |
outboxJobs | dueLagSeconds | As above, for jobs | more than 900 seconds |
qstash | publisher / receiver | Push delivery configuration | missing in production (deliveries fall back to the one-minute sweep) |
A delivery waiting out its retry backoff is not counted as late. A delivery buffered for a
disabled endpoint is neither late nor part of pending: it waits for the endpoint's owner, so it
does not degrade the status. Avrix operations are alerted from the same evaluation, so a degraded queue is already being
worked on; watch it to explain a delay you see, not to page Avrix.
What GET /usage reports#
GET /usage counts every response your keys received in the window, from the same call log: successes, reads and denials alike, for the key owner in the calling key's environment. The window is UTC, both ends inclusive, by default the last 7 days; the call log is kept for 90 days. The totals and these breakdowns always cover the whole window:
| Field | One entry per | Use it for |
|---|---|---|
byRoute | Method and route template (/v1/orders/{id}) | Which operations a store calls, whatever the ids |
byStatus | HTTP status and error code (422 VALIDATION_FAILED, 429 RATE_LIMIT_EXCEEDED) | What failed and why; a response recorded before codes were stored reports HTTP_<status> |
byDay | UTC day | Trends and spikes |
byKey | API key | Which key or deployment makes the traffic |
errors counts responses of 400 and above, except GET 404 lookup misses, which are counted
apart (lookupMisses). byEndpoint keeps path parameters as sent (each id is its own entry) and
lists at most maxEndpointBuckets entries, largest first; truncated is true when it leaves
some out. maxCountedRequests is deprecated: totals are no longer capped. Pass keyId to count
one of your keys.
Use usage and activity for capacity and ops dashboards, and requests/{requestId} when
correlating a support ticket.