Quickstart

About 15 minutes from health check to your first fulfilled order.

Place a real, fulfilled order against the Avrix sandbox and receive a key. Every command below is complete and can be pasted into a terminal.

Time: about 15 minutes. You will end with: a delivered game key, a verified webhook, and a reconciled order record.

Before you start#

You need three things. If you have all three, skip to step 1.

RequirementHow to get it
An Avrix Console account with a seller companyYour Avrix onboarding contact creates this during account setup
A sandbox API keyConsole → Settings → Integrations → API Keys → Create key, Environment Sandbox, scopes seller:products:read, seller:orders:write, seller:webhooks:write
A terminal with curl and jqjq is optional but the examples use it for readability
Optional: an official SDKTypeScript, Python or PHP — steps 4, 6 and 8 show each one next to cURL. The packages are not on npm, PyPI or Packagist yet; Official SDKs says how to get a build. Every step works with cURL alone

The sandbox catalog is a shared fixture catalog. You do not need a vendor agreement, an allocation, or a territory price list to complete this quickstart — the fixtures already have them. See Authentication for the full credential model.

Set up your shell:

Bash
export AVRIX_BASE_URL="https://api.avrix.io"
export AVRIX_API_KEY="avrix_sk_your_key_here"

Paste the key exactly as the console displayed it. Do not add a Bearer prefix, quotes, or any character the console did not show — the most common first-call failure is a stray character in the Authorization header.

Step 1 — Confirm connectivity#

Bash
curl -s "$AVRIX_BASE_URL/api/seller/v1/health"
JSON
{ "status": "ok" }

This endpoint needs no authentication. If it fails, the problem is network or DNS, not credentials. The public status page shows the same health per capability (orders, catalog, webhooks, sandbox) with incident history.

Step 2 — Confirm your credential#

curl -s -X GET "https://api.avrix.io/api/seller/v1/whoami" \
  -H "Authorization: Bearer $AVRIX_API_KEY"
JSON
{
  "data": {
    "company": {
      "id": "acme-games",
      "name": "Acme Games"
    },
    "sandbox": true,
    "hasActiveBma": true,
    "key": {
      "id": "4d7e2f10-8a3b-4c5d-9e6f-0a1b2c3d4e5f",
      "name": "Store backend",
      "environment": "sandbox",
      "scopes": [
        "seller:finance:read",
        "seller:keys:pull",
        "seller:keys:write",
        "seller:orders:fulfill",
        "seller:orders:manage",
        "seller:orders:preview",
        "…"
      ],
      "rateLimited": true,
      "allowedIps": []
    },
    "capabilities": {
      "preorderEnabled": true,
      "backorderEnabled": true,
      "checkoutHoldEnabled": true,
      "priceCommitmentConfigured": true,
      "territoryEnforcementEnabled": true,
      "consumerGeoEnforcementEnabled": false
    },
    "integrationReadiness": {
      "sellableSkuCount": 19,
      "sharedSkuCount": 19,
      "allocatedSkuCount": 19,
      "allocatedWithoutShareCount": 0,
      "sharedWithoutAllocationCount": 0,
      "missingTerritoryPricingCount": 0,
      "blockers": [],
      "settlementHint": "invoice_report_only",
      "settlementMode": "automated_invoice",
      "diagnostics": false
    },
    "warnings": []
  }
}

Check three things before continuing. environment must be sandbox. scopes must contain seller:products:read and seller:orders:write (a key issued with the older seller:keys:pull instead works the same way). capabilities tells you which optional flows are available on your account — you will not use them in this quickstart, but every guide that describes an optional capability tells you which field to check.

A 401 here means the key is wrong, revoked, or from the other environment. A 403 means the key has no scopes. Both are covered in Authentication.

Step 3 — Find something to sell#

The sandbox provides deterministic magic SKUs. Use SANDBOX-ALWAYS-001, which has a continuously replenished key pool and will not run dry while you are testing.

Bash
curl -s "$AVRIX_BASE_URL/api/seller/v1/allocations?sellableOnly=true&limit=5" \
  -H "Authorization: Bearer $AVRIX_API_KEY" | jq '.data[] | {skuCode, sellable, businessModel, pricePerKeyCents, remaining}'
JSON
{
  "skuCode": "SANDBOX-ALWAYS-001",
  "sellable": true,
  "businessModel": "api",
  "pricePerKeyCents": null,
  "remaining": 99412
}

Under the API business model there is no wholesale price on the allocation: pricePerKeyCents is null and your cost is a share of the territory list price. The price you charge and echo comes from preview (unitPriceCents, 5999 for this SKU in the sandbox) — step 4. A wholesale or pre_order allocation is where pricePerKeyCents carries the contract price.

Step 4 — Preview before you charge#

Preview tells you whether the order can be fulfilled right now and what price Avrix will hold you to. Call it when the buyer reaches checkout, not on every page view.

Every API-model preview and order carries an integrationOrderContext with the gross price you charge the buyer (salesPriceGrossMinor), the tax rate you applied (salesTaxRatePercent, 0 where no tax applied) and the channel the sale came through (salesChannel). These are required in Sandbox and in Production alike; omitting them is refused with TAX_DECLARATION_REQUIRED or SALES_CHANNEL_REQUIRED before any key moves. Production keys additionally declare the buyer's IP as consumerIp (top level or inside the context); see Order context.

curl -s -X POST "$AVRIX_BASE_URL/api/seller/v1/orders/preview" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skuCode": "SANDBOX-ALWAYS-001",
    "quantity": 1,
    "countryCode": "US",
    "integrationOrderContext": {
      "schemaVersion": 1,
      "salesCountryCode": "US",
      "currencyCode": "USD",
      "salesPriceGrossMinor": 7999,
      "salesTaxRatePercent": 0,
      "salesChannel": "web"
    }
  }' | jq
JSON
{
  "data": {
    "type": "order_preview",
    "fulfillmentType": "fulfilled",
    "allocationId": "07ea0905-152b-8f0d-8261-78eb28f91f27",
    "allocationRemaining": 999768,
    "inventoryAvailable": 100,
    "maxFulfillableQuantity": 100,
    "canFulfill": true,
    "partialFulfillmentExpected": false,
    "cannotFullyFulfill": false,
    "allOrNothingWillFail": false,
    "lines": [
      {
        "skuId": "07ea0816-162b-8822-8385-1d0609d86dd3",
        "skuCode": "SANDBOX-ALWAYS-001",
        "quantity": 1,
        "unitPriceCents": 5999,
        "lineTotalCents": 5999,
        "currencyCode": "USD",
        "currencyExponent": 2,
        "initialUnitPriceCents": 5999,
        "promo": null,
        "promoResolution": "none",
        "listPromo": null,
        "advertisedUnitPriceCents": 5999,
        "activation": {
          "type": "worldwide",
          "countries": null
        }
      }
    ],
    "totalCents": 5999,
    "currencyCode": "USD",
    "currencyExponent": 2,
    "priceCommitment": {
      "token": "pct1.<token>",
      "expiresAt": "2026-09-06T13:31:39.000Z"
    },
    "priceCommitmentToken": "pct1.<token>",
    "estimateOnly": true
  }
}

Two fields decide what happens next.

canFulfill must be true before you charge the buyer. If it is false, Avrix cannot deliver the requested quantity and POST /orders will fail — Avrix never partially fulfils. Disable the pay button or reduce the quantity.

unitPriceCents is the price you must echo back on the order as expectedUnitPriceCents. This is how Avrix guarantees you are never charged a price you did not see. If the price moves between preview and order, the order is rejected rather than silently repriced.

Step 5 — Charge the buyer#

This step happens entirely in your own system, at your own payment processor. Avrix is not involved and has no visibility into it.

Capture the payment reference your processor returns — you will send it to Avrix as commercial evidence. In sandbox a placeholder is accepted; in production a real reference is required.

Step 6 — Create the order#

curl -s -X POST "$AVRIX_BASE_URL/api/seller/v1/orders" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-order-10432" \
  -d '{
    "skuCode": "SANDBOX-ALWAYS-001",
    "quantity": 1,
    "orderReference": "store-order-10432",
    "expectedUnitPriceCents": 5999,
    "countryCode": "US",
    "integrationOrderContext": {
      "schemaVersion": 1,
      "salesCountryCode": "US",
      "currencyCode": "USD",
      "salesPriceGrossMinor": 7999,
      "salesTaxRatePercent": 0,
      "salesChannel": "web",
      "paymentProcessorReference": "sandbox_pay_10432",
      "checkoutSessionId": "cs_sandbox_10432"
    }
  }' | jq
JSON
{
  "data": {
    "type": "fulfilled",
    "skuCode": "SANDBOX-ALWAYS-001",
    "orderReference": "store-order-10432",
    "pulled": 1,
    "keys": ["SBOX-ATZQ4-9WFKD-2M7XR"],
    "keyIds": ["8f21a9b0-1234-5678-9abc-def012345678"]
  }
}

Three parts of that request deserve attention.

Idempotency-Key makes the request safe to retry. Send the same value with the same body and you get the original result back rather than a second fulfilment. The SDK order helpers retry for you with the same key and body, and recover the keys when the response is lost (step 7). Use a value that is stable for the logical order — your checkout session id is ideal. Integration recipes covers the full contract.

orderReference is your business identifier. It is immutable, it appears on finance records, and it is how you look the order up later. It is not a substitute for the idempotency key; the two do different jobs.

integrationOrderContext declares the retail transaction: what the buyer paid, where they were, and which payment it corresponds to. Sandbox and production keys both require the sale country, gross price, tax rate and sales channel; production keys also require the net price, tax amount, payment references and buyer IP. The one table of what each key must send is in Sandbox.

Step 7 — Verify the order#

Bash
curl -s "$AVRIX_BASE_URL/api/seller/v1/orders?orderReference=store-order-10432" \
  -H "Authorization: Bearer $AVRIX_API_KEY" | jq

This is also your recovery path. If step 6 ever times out and you do not know whether it succeeded, do not re-charge and do not issue a new idempotency key. Either replay the identical request with the identical key, or look the order up by reference and re-read lost keys with POST /orders/recover-keys. The SDK order helpers in step 6 run exactly this sequence and only report a refund as safe when Avrix confirmed no live keys exist. See Order lifecycle.

Step 8 — Receive a webhook#

Register an endpoint to receive asynchronous outcomes. Use any HTTPS URL you control; a request inspector works for this test.

Bash
curl -s -X POST "$AVRIX_BASE_URL/api/seller/v1/webhooks" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-setup-1" \
  -d '{
    "url": "https://your-endpoint.example.com/avrix/webhooks",
    "events": ["order.fulfilled", "order.failed"]
  }' | jq
JSON
{
  "data": {
    "id": "wh_7d3f...",
    "url": "https://your-endpoint.example.com/avrix/webhooks",
    "events": ["order.fulfilled", "order.failed"],
    "secret": "whsec_2fA...",
    "status": "active"
  }
}

Send a test delivery:

Bash
curl -s -X POST "$AVRIX_BASE_URL/api/seller/v1/webhooks/wh_7d3f.../test" \
  -H "Authorization: Bearer $AVRIX_API_KEY" | jq

Your endpoint receives a test.ping with an X-Avrix-Signature header. Verify that signature before trusting any webhook body. Pass the raw body exactly as received; while you rotate the endpoint secret the header carries one v1 signature per secret, and the SDK verifiers accept either:

import { verifyAvrixWebhookSignature } from "@avrix/seller-api-helpers";

export async function POST(request: Request): Promise<Response> {
  // The body exactly as received, never re-serialised JSON. During a secret
  // rotation the header carries one v1 per secret; any match passes.
  const rawBody = await request.text();
  const verdict = await verifyAvrixWebhookSignature(
    process.env.AVRIX_WEBHOOK_SECRET!,
    request.headers.get("X-Avrix-Signature"),
    rawBody,
  );
  if (!verdict.ok) return new Response(verdict.code, { status: 401 });
  await enqueue(JSON.parse(rawBody)); // dedupe on eventId
  return new Response(null, { status: 200 });
}

The full delivery contract (retries, ordering, deduplication) is in the webhook guide.

You are done#

You have completed the full transaction cycle: catalog, preview, order, fulfilment, and events.

What to build next#

NextWhy
Catalog and allocationsYour real catalog is not one call — get the sync model right before writing it
Order lifecycleEvery failure mode, including price drift, sold-out inventory, and unknown outcomes
Webhook guideSignature verification, retries, deduplication
Error referenceEvery code, when it occurs, and whether retrying is safe
Sandbox to productionWhat changes when you go live, and what certification requires

Try a failure path#

The sandbox includes deterministic failure fixtures. Running these now is cheaper than discovering them in production.

SKUProduces
SANDBOX-NOKEYS-001409 NO_AVAILABLE_KEYS — the post-payment refund path
SANDBOX-PRICE-MIS-001Price mismatch when expectedUnitPriceCents is stale
SANDBOX-NOALLOC-001Shared but unallocated — sellable: false
SANDBOX-LIFECYCLE-001Product not live — PRODUCT_NOT_SELLABLE
SANDBOX-TERR-BLOCK-001Territory rejection — price list is DE-only, so send US

What links here

Published guides that link to this page.

Search docs

Search documentation…