Integration recipes

Scopes, call order, and idempotency for each flow.

TopicsReference

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.


Recipe: browse-catalog#

FieldValue
DescriptionDiscover partners and products, then load detail and regional pricing.
Scopesseller:products:read
IdempotencyNot applicable (GET only).

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 countryCode=US,DE (country is the deprecated spelling).

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 metadata and lifecycle deltas. Price changes never move updatedAt — poll GET /catalog/changes?cursor= (persist the snapshot's meta.changesCursor, then each page's meta.nextCursor) and refetch GET /products/{productId}/pricing for entries with changedFields: ["pricing"]; sku.pricing_updated pushes the same change. 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.


Recipe: check-before-pull#

FieldValue
DescriptionVerify allocation + inventory headroom before pulling keys.
Scopesseller:products:read (for SKU identity) and seller:orders:write for pull endpoints (legacy seller:keys:pull also accepted).
IdempotencyNot applicable for GET /availability.

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.

Recipe: pull-keys#

FieldValue
DescriptionPull keys from an allocation (non-order flow).
Scopesseller:orders:write (legacy seller:keys:pull also accepted)
IdempotencyRequired for safe retries: Idempotency-Key header on POST /keys/pull (same rules as orders).

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

Recipe: create-order#

FieldValue
DescriptionCreate an order and receive keys (primary purchase flow).
Scopesseller:orders:write (legacy seller:keys:pull also accepted), and typically seller:products:read to resolve SKUs.
IdempotencyRequired: Idempotency-Key on POST /orders — retries must reuse the same key to receive the cached response.

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.

Recipe: pre-order#

FieldValue
DescriptionSell a SKU that is not yet released. With POST /orders the order waits without keys until inventory covers it; you then fulfil it. A pre-order line of POST /orders/bulk reserves keys at once and is delivered automatically at release. See pre-orders.
Scopesseller:orders:write (legacy seller:keys:pull also accepted)
IdempotencyIdempotency-Key on POST /orders (or /orders/bulk). Idempotency-Key on POST /orders/cancel to cancel reservations safely.

Order of calls

  1. Optional: GET /availability — pre-order SKUs may show reserved paths per product rules.
  2. POST /orders — response type: "pre-order", status: "awaiting_release" and an orderId; no keys.
  3. Optional: POST /orders/cancel with { "orderReference": "<your id>" } — webhook order.cancelled (also delivered as its older name order.returned).
  4. On order.ready: POST /orders/{orderId}/fulfill with an Idempotency-Key; the response carries the keys. Nothing is delivered until you call it.
  5. Key-locked pre-orders (bulk lines) skip step 4: on order.preorder_fulfilled, read the keys with POST /orders/recover-keys.

Recipe: get-order#

FieldValue
DescriptionReconcile a store order id against Avrix pulls and reservations.
Scopesseller:orders:read (also seller:orders:write; legacy seller:products:read, seller:keys:pull)
IdempotencyGET only.

Order of calls

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

Recipe: return-keys#

FieldValue
DescriptionReturn keys after fulfillment (refund/chargeback flows). See Key return policy.
Scopesseller:refunds:write (also seller:orders:write; legacy seller:keys:pull still accepted)
IdempotencyIdempotency-Key on POST /keys/return.

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

Recipe: recover-keys#

FieldValue
DescriptionYour store lost the POST /orders response (crash between the pull and your own database write) and needs the keys it already paid for.
Scopesseller:orders:write (legacy seller:keys:pull also accepted)
IdempotencyNot required — the call never pulls new inventory; every call is audited as a key reveal.

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.

Recipe: list-history#

FieldValue
DescriptionAudit key pulls and orders via transactions.
Scopesseller:orders:read (also seller:orders:write; legacy seller:products:read, seller:keys:pull)
IdempotencyGET only.

Order of calls

  1. GET /keys/pulls (older path GET /transactions) — paginate with cursor, filter orderReference, from, to as needed (one row per key pulled; keyPullId names the pull, transactionId the sale row).

Recipe: promotions#

FieldValue
DescriptionReview and answer platform event shares and custom deals, then show their prices while they are live.
Scopesseller:promotions:read for GET; seller:promotions:respond for accept / decline / respond.
IdempotencyPOST accept/decline/respond accept an optional Idempotency-Key: send one per decision and reuse it on retries. On contract date 2026-12-01 a repeat without a key is safe too (same answer 200, different answer 409).

Order of calls

  1. Subscribe a webhook endpoint to the promotion.* events, or poll the lists below with updatedSince and sort=updatedAt
  2. GET /promotions/summary
  3. GET /promotions/shares?status=pending → GET /promotions/shares/{shareId} → POST .../accept or .../decline before respond_by
  4. GET /promotions/deals?status=pending → GET /promotions/deals/{responseId} → POST .../respond before respond_by
  5. After accepting: GET /promotions/calendar?window=live,upcoming and GET /promotions/shares/{shareId}/discounts to stage the sale; on promotion.started show advertisedPriceCents from GET /products/{productId}/pricing; on promotion.ended go back to the list price

Recipe: webhooks#

FieldValue
DescriptionRegister HTTPS endpoints for Seller API events.
Scopesseller:webhooks:read, seller:webhooks:write
IdempotencyNot specified for webhook CRUD; use unique URLs per endpoint.

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.

Recipe: usage#

FieldValue
DescriptionAggregate API call counts from audit logs (per endpoint, errors).
Scopesseller:products:read
IdempotencyGET only.

Order of calls

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

Recipe: manage-api-keys#

FieldValue
DescriptionList, create, or revoke seller API keys via the API.
Scopesseller:keys:write on the calling key
IdempotencyFollow OpenAPI for POST /keys; protect create with your own deduplication if needed.

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.

Generated TypeScript client#

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

What links here

Published guides that link to this page.

Search docs

Search documentation…