Integration recipes

Canonical user journeys for the Seller API (GET /api/seller/v1/openapi). Each recipe lists scopes, call order, and idempotency so humans, agents, and generated clients stay aligned.

New to the API? Follow 30-minute quickstart first (health → partners → products → order → webhooks). For storefront call sequences, see Store integration profiles.

OpenAPI (canonical): GET /api/seller/v1/openapi (e.g. https://api.avrix.io/api/seller/v1/openapi).
Interactive docs (canonical): GET /api/seller/v1/docs on the same host.

Unversioned URLs (/api/seller/openapi, /api/seller/docs) redirect to the v1 paths; prefer the v1 URLs in new integrations.

All paths below are under /api/seller/v1/ unless noted. Prefer response field data for lists; legacy top-level keys are deprecated.

Order of calls

1. GET /partners — connected vendors (data[]: publisherCompanyId legacy field name, …).
2. GET /products — paginate with cursor / limit; optional partner, q, status, updatedSince (ISO 8601 incremental sync).
3. GET /products/{productId} — editions, releases, SKUs; optional expand=base.
4. GET /products/{productId}/pricing — per release / country; optional country=US,DE.

Incremental sync: Store the latest of each product’s updatedAt / createdAt (from detail or list) or the webhook product.updated payload updatedAt, then call GET /products?updatedSince=... on a schedule to fetch deltas. Full scans are optional.

Very large catalogs: Prefer partner (iterate per vendor), q, or slug to parallelize jobs. Pagination is keyset (stable pages). See Catalog sync & caching.

Order of calls

1. Obtain skuCode or skuId from product detail (GET /products/{productId}).
2. GET /availability?skuCode=... or ?skuId=... — read data.available, allocationRemaining, inventoryAvailable (sum of dedicatedAvailable + sharedPoolAvailable), maxFulfillableQuantity, and backorderEligible.
3. For a cart line quantity q, add &quantity=q — use data.canFulfill before enabling Pay; when cannotFullyFulfill (alias allOrNothingWillFail) is true, POST /orders returns 409 NO_AVAILABLE_KEYS with zero keys — orders are all-or-nothing, never partial. partialFulfillmentExpected is the deprecated name for the same boolean and does not mean partial delivery.
4. Optional checkout race reduction: after Order preview, call POST /orders/hold when whoami.capabilities.checkoutHoldEnabled is true.

Order of calls

1. Optional: GET /availability (recipe check-before-pull).
2. POST /keys/pull with body per OpenAPI — include Idempotency-Key (UUID or 1–64 alphanumeric characters).

External stores (game shops, first-party storefronts): send a full body for reconciliation and finance evidence: orderReference, metadata, and especially integrationOrderContext (declared retail country, currency, gross/net minors). Production keys require commercial evidence fields; sandbox keys do not: see Sandbox and environments.

Order of calls

1. POST /orders/preview — do not charge unless canFulfill is true.
2. Optional: POST /orders/hold then pass checkoutHoldId on POST /orders when checkout hold is enabled (whoami.capabilities.checkoutHoldEnabled).
3. POST /orders with Idempotency-Key and your orderReference.

Order of calls

1. Optional: GET /availability — pre-order SKUs may show reserved paths per product rules.
2. POST /orders — response type: pre-order when keys are reserved (not plaintext in response).
3. Optional: POST /orders/cancel with { "orderReference": "<your id>" } — releases reservations; webhook order.returned.
4. Otherwise: wait for release — order.preorder_fulfilled / order.fulfilled when keys are delivered (cron-driven unlock).

Order of calls

1. GET /orders?orderReference=<your store order id> — aggregated lines (fulfilled pulls, active pre-order reservations).

Order of calls

1. POST /keys/return with required keyIds (from the fulfilled order response or order.fulfilled webhook) and optional reason. The body does not accept orderReference.
2. Alternatively POST /refunds with type, refundReference and either keyIds or quantity + orderReference — the latter quarantines the newest quantity live keys sold under that reference (partial refunds without tracking key ids by position).

Order of calls

1. GET /orders?orderReference=<your store order id> — confirms status: "fulfilled" (never returns plaintext).
2. POST /orders/recover-keys { "orderReference": "<your store order id>" } — returns the live keys and keyIds sold under that reference. Returned / refunded keys are excluded; 404 NOT_FOUND means nothing is live under the reference.
3. Re-posting POST /orders with the same orderReference and the same quantity replays the same keys as well (documented idempotent replay); prefer recover-keys because it needs no price binding.

Order of calls

1. GET /transactions — paginate with cursor, filter orderReference, from, to as needed (one row per key pulled).

Order of calls

1. GET /promotions/summary
2. GET /promotions/shares → GET /promotions/shares/{shareId} → POST .../accept or .../decline
3. GET /promotions/deals → GET /promotions/deals/{responseId} → POST .../respond

Order of calls

1. GET /webhooks
2. POST /webhooks to create
3. DELETE /webhooks/{id} to remove

Optional

• POST /webhooks/{id}/test — queue a test.ping delivery to verify URL + signature.
• PATCH /webhooks/{id} — update url / events, or rotateSecret: true for a new signing secret.
• POST /webhooks/{id}/enable — re-enable after automatic disable (circuit breaker).
• POST /webhooks/{id}/deliveries/{deliveryId}/retry — retry a failed delivery.

Order of calls

1. GET /usage?from=...&to=... (ISO 8601 UTC; defaults to last 7 days).

Order of calls

1. GET /keys
2. POST /keys / DELETE /keys/{id}

Create behavior (POST /keys)

• Body: name (required), optional allowed_ips (string array), optional includeFinanceScope.
• New keys receive the server default scope set intersected with the calling key’s scopes (children never exceed the parent ceiling). See API key management.

Prefer a typed client generated from OpenAPI, or plain fetch. See Client & helpers.

• Order preview — read-only checkout estimate before POST /orders
• Catalog sync & caching — snapshot + allocations sync pattern
• Webhooks — push-first fulfillment and catalog deltas
• 30-minute quickstart — end-to-end golden path through these recipes
• SDK & helpers — generated TypeScript client and transport helpers