Monitoring & support

What to alert on, requestId correlation, and escalation.

TopicsOperate

What to watch in production, how to correlate failures, how to escalate, and what Avrix will (and will not) promise in public docs.

Support#

ChannelUse
support@avrix.ioProduction incidents, integration blockers, certification evidence hand-off
Your Avrix partner / pilot contactPilots 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:

SignalWhere you can see it
Order placement availabilityStatus page, "Order placement"; components.orderPath
Webhook delivery latency, event created → delivered (p95 and p99, last hour)components.webhookDelivery.deliveryP95Seconds / deliveryP99Seconds
API key revocation taking effectWithin about 60 seconds of revoking or rotating a key (Authentication)
Recovery after a failed checkout that already charged the buyerRetry 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.notice webhook event: add it to an endpoint's events and 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#

SignalWhy
POST /orders success rateBuyer-facing fulfilment health
409 NO_AVAILABLE_KEYS after chargePreview / 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 rateSync too aggressive for the per-key limits (see Rate limits); ask Avrix about launch headroom
Idempotency mismatches / in-flightClient retry bugs
Webhook delivery failure rateEndpoint down, signature bugs, slow handlers
Pull velocity anomaliesCompromised 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.

Prioritise these in production:

  1. Webhook delivery failures — sustained non-2xx or auto-disable on your endpoint
  2. 402 / 409 rate — especially NO_AVAILABLE_KEYS after a successful PSP charge
  3. Reconciliation drift — local paid orders missing from GET /orders (or the reverse)
  4. 429 spikes — 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:

FieldExample
requestId / X-Request-Idreq_01J8XYZ...
orderReferencestore-order-10432
Approximate UTC timestamp2026-08-05T09:14:22Z
Environmentsandbox / production
API key id (not the secret)From Console → Settings → Integrations → API Keys
Route + HTTP status + error codePOST /orders → 409 NO_AVAILABLE_KEYS

Looking a request up#

GET /api/seller/v1/requests/{requestId} answers from two records, both kept for 90 days:

RecordWhat it holdsWhich requests
callLogMethod, endpoint, status, latency, error code and key idEvery 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).
tracesThe fields an order or refund needs: orderReference, outcome (fulfilled, preordered, backordered, deferred, replayed, reserved, refunded, returned), keyPullId, pulledCountSampled; 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:

RequestTrace kept
A write (POST, PATCH, PUT, DELETE) on the order, key pull, key export, key return, refund or webhook routesAlways. A successful POST /orders/preview counts as a read.
An error response the route records on those same routesAlways
A 429, or a 5xx the route records, on any other routeAlways
Another 4xx response on any other routeAbout 1 in 10
A successful response (2xx, 3xx) on any other route, and a successful read on the routes in the first rowAbout 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#

  1. Self-serve — check GET /whoami, deliveries list, GET /orders?orderReference=, catalog changes.
  2. Replay — webhook delivery replay for missed push events (metadata only).
  3. Support — email support@avrix.io (or your partner contact) with the correlation table above.
  4. 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#

CheckRoute
Platform upGET /api/seller/v1/health (no auth)
Key / company / capabilitiesGET /api/seller/v1/whoami
Can the company sell yetGET /api/seller/v1/integration/status
Egress IP discoveryGET /api/seller/v1/whoami-ip
Usage summaryGET /api/seller/v1/usage
Activity feedGET /api/seller/v1/activity
Redacted request traceGET /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.

QuestionCallRead
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 /whoamirequiredDeclarationsByOperation
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:

ComponentFieldMeaningDegraded when
webhookDeliverypendingDeliveries still to send; leaves out deliveries buffered for a disabled endpointmore than 5,000 pending
webhookDeliverybufferedDeliveries held for disabled endpoints until they are re-enabled (see Webhooks)informational
webhookDeliverydueLagSecondsHow long the oldest delivery that is already due has waited past its due timemore than 900 seconds
webhookDeliveryfailedLast24hDeliveries that exhausted their retries in the last dayinformational
outboxJobspendingBackground jobs (catalog exports, settlement follow-ups) still to runmore than 500 pending
outboxJobsdueLagSecondsAs above, for jobsmore than 900 seconds
qstashpublisher / receiverPush delivery configurationmissing 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:

FieldOne entry perUse it for
byRouteMethod and route template (/v1/orders/{id})Which operations a store calls, whatever the ids
byStatusHTTP 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>
byDayUTC dayTrends and spikes
byKeyAPI keyWhich 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.

What links here

Published guides that link to this page.

Search docs

Search documentation…