AvrixDocumentation
API referenceStatusAvrix.ioConsole
Seller API

Welcome

  • Home
  • Getting started
  • Topic index
  • Glossary

Get started

  • Overview
  • How Avrix works
  • Architecture patterns
  • Quickstart
  • Integration tutorial
  • Authentication
  • OAuth tokens
  • Environments
  • Sandbox

Connect a partner

  • Partner onboarding
  • Sellable SKU readiness
  • Territory enforcement
  • AI assistants (MCP)
  • Connect your AI client
  • Sign-in and permissions

Catalog

  • Catalog & allocations
  • Product field matrix
  • Pricing authority
  • Currency and FX
  • Promotions
  • Caching & fairness

Sell an order

  • Store integration profiles
  • Order preview
  • Creating orders
  • Idempotency
  • Order context
  • Checkout holds
  • Hot drop
  • Fulfillment & keys
  • Keyless fulfilment
  • Order lifecycle
  • Refunds & returns

Stay in sync

  • Webhooks
  • Event reference
  • Polling & reconciliation
  • Reconciliation
  • Finance & settlement

Operate

  • Error reference
  • Troubleshooting
  • Key recovery
  • Rate limits
  • Security
  • Secrets & config
  • API key management
  • IP allowlist
  • Monitoring & support
  • Data handling
  • Partner runbook

Go live

  • Testing
  • Certification
  • Integration checklist
  • Sandbox to production
  • Go-live
  • Deployment targets

Reference

  • Integration recipes
  • Scope matrix
  • Commerce platforms
  • API clients
  • Client & helpers
  • Versioning
  • Changelog
  • FAQ
  • API reference

Search docs

Search documentation…

  1. Home
  2. /Reference
  3. /Client & helpers

Client & helpers

Generate a typed client from OpenAPI and implement production HTTP patterns.

TopicsReference

Note: @avrix/seller-api-client and @avrix/seller-api-helpers are not published to npm. Generate a typed client from the OpenAPI document, and implement the HTTP patterns below (or vendor the in-repo helper sources if you have repository access). Every example on this site works with plain fetch.

For production client patterns in TypeScript, Python, PHP, Go, Java, and C#, see API clients and Architecture patterns. Multi-language tabs on this site remember your last language choice.

Example#

# Prefer env vars — never hardcode secrets in source control
export AVRIX_API_KEY="avrix_sk_sbx_your_key_here"
export AVRIX_BASE_URL="https://api.avrix.io"

Generating a typed client#

The OpenAPI document is the contract, and it is served live by your API host:

  • Interactive docs: https://api.avrix.io/api/seller/v1/docs
  • OpenAPI JSON download: https://api.avrix.io/api/seller/v1/openapi

Point any OpenAPI generator at that JSON to produce a typed client in your language of choice, and regenerate whenever info.version changes. Generated clients inherit the same X-Api-Version compatibility policy as the raw API — see Versioning and compatibility.

Postman#

Avrix provides a ready-made Seller API Postman collection for manual exploration. Import it into Postman, point the environment baseUrl at https://api.avrix.io, and set apiKey to the raw key only (the collection adds the Bearer prefix). Use a sandbox key for everyday testing and a production key only after go-live. Ask your Avrix contact if you need the collection file or a shared workspace copy.

When to generate a client vs use fetch#

ApproachBest for
Generated clientLarge integrations, typed requests, refactors
Raw fetch or PostmanQuick tests, minimal dependencies, other languages

Both are valid; the contract is always GET /api/seller/v1/openapi.

Behaviours a production client needs#

Whether you generate a client or use fetch, implement these behaviours:

BehaviourWhy
Retry on 429 / 502 / 503 / 504Honour Retry-After with backoff
Stable Idempotency-Key on writesPrevents duplicate fulfilment on retries — Idempotency
Webhook signature verificationHMAC-SHA256 on the raw body — Webhooks
Catalog sync = snapshot + allocationsShared SKUs alone are not the sellable set — Catalog and allocations
Preview before chargeGate on canFulfill — Order preview

HTTP patterns (copy-paste)#

Authenticated request with retries#

TypeScript
async function sellerFetch(
  path: string,
  init: RequestInit & { idempotencyKey?: string } = {},
): Promise<Response> {
  const headers = new Headers(init.headers);
  headers.set("Authorization", `Bearer ${apiKey}`);
  if (init.idempotencyKey) headers.set("Idempotency-Key", init.idempotencyKey);
  if (init.body && !headers.has("Content-Type")) {
    headers.set("Content-Type", "application/json");
  }

  let attempt = 0;
  while (true) {
    const res = await fetch(`https://api.avrix.io${path}`, { ...init, headers });
    if (res.status !== 429 && res.status < 500) return res;
    attempt += 1;
    if (attempt > 5) return res;
    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    await new Promise((r) => setTimeout(r, Math.min(30, retryAfter) * 1000));
  }
}

await sellerFetch("/api/seller/v1/whoami");

Preview → charge → order#

TypeScript
const previewRes = await sellerFetch("/api/seller/v1/orders/preview", {
  method: "POST",
  body: JSON.stringify({
    skuCode: "SANDBOX-ALWAYS-001",
    quantity: 1,
    countryCode: "US",
  }),
});
const previewJson = await previewRes.json();
if (!previewJson.data?.canFulfill) {
  throw new Error("Do not charge — Avrix cannot fulfil");
}

// Charge at your PSP, then:
const orderRes = await sellerFetch("/api/seller/v1/orders", {
  method: "POST",
  idempotencyKey: "ik_store_10432",
  body: JSON.stringify({
    skuCode: "SANDBOX-ALWAYS-001",
    quantity: 1,
    orderReference: "store-order-10432",
    countryCode: "US",
    expectedUnitPriceCents: previewJson.data.unitPriceCents,
    priceCommitmentToken: previewJson.data.priceCommitmentToken,
    integrationOrderContext: {
      schemaVersion: 1,
      salesCountryCode: "US",
      currencyCode: "USD",
      salesPriceGrossMinor: 1999,
      salesPriceNetMinor: 1999,
      priceIncludesTax: true,
      salesTaxAmountMinor: 0,
      salesTaxRatePercent: 0,
      salesChannel: "web",
      consumerIp: "203.0.113.42",
      paymentMethodFamily: "card",
      paymentProcessorReference: "psp_txn_10432",
      checkoutSessionId: "cs_store_10432",
    },
  }),
});

Catalog sync (HTTP algorithm)#

  1. Page through GET /catalog/snapshot (or GET /products).
  2. Page through GET /allocations and merge on SKU id — authoritative sellable.
  3. Persist a watermark and call GET /catalog/changes?since= for deltas (including tombstones).

Never treat /products alone as the sellable catalog.

Related#

  • Quickstart — golden path using raw fetch or a generated client
  • Integration recipes — scopes, call order, and idempotency per flow
  • Webhooks — signature verification and delivery semantics
  • Partner runbook — keep OpenAPI and client artifacts in sync

What links here

Published guides that link to this page.

  • API clientsProduction HTTP client patterns per language — config, reuse, and retries.
  • Integration recipesScopes, call order, and idempotency for each flow.
  • Product field matrixWhich product fields appear on list, detail, allocations, and webhooks.
  • Store integration profilesProfile A/B/C checkout patterns — preview, hold, and hot-drop.
PreviousAPI clientsNextVersioning & compatibility

Need help with this page?

Contact support

AI tools

  • Ask ChatGPT
  • Ask Claude

On this page

  • Example
  • Generating a typed client
  • Postman
  • When to generate a client vs use `fetch`
  • Behaviours a production client needs
  • HTTP patterns (copy-paste)
  • Authenticated request with retries
  • Preview → charge → order
  • Catalog sync (HTTP algorithm)
  • Related

Related pages

  • QuickstartAbout 15 minutes from health check to your first fulfilled order.
  • Integration recipesScopes, call order, and idempotency for each flow.
  • Catalog & allocationsThe four gates that make a SKU sellable, and how to sync them.
  • Partner runbookSandbox vs production, strict mode, and operational checks.