Integration tutorial

End-to-end walkthrough from authentication to reconciliation, including failure paths.

An end-to-end Seller API walkthrough. Every step uses the same scenario: one key of one sandbox SKU, sold to a buyer in the Netherlands.

FieldValue
API keyavrix_sk_sbx_your_key_here
SKUSANDBOX-ALWAYS-001
orderReferencestore-order-10432
Buyer countryNL
CurrencyEUR
Retail price you charge7999 (EUR 79.99, including 21% VAT of 1388)
Base URLhttps://api.avrix.io

Replace the key placeholder with a sandbox secret from the Console. All paths are under /api/seller/v1.

Example: the catalog#

The two calls every integration starts with: the catalog snapshot, then your allocations. Step 2 explains how to merge them.

curl -s -X GET "https://api.avrix.io/api/seller/v1/catalog/snapshot" \
  -H "Authorization: Bearer $AVRIX_API_KEY"
curl -s -X GET "https://api.avrix.io/api/seller/v1/allocations" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Golden path in one diagram#

The call sequence below is the same golden path as the sequence diagram on Overview: sync catalog + allocations → preview (canFulfill) → charge at your PSP → POST /orders with a stable Idempotency-Key → persist keys from the HTTP response → webhooks + reconcile. Use that diagram for the picture; this page is the worked sandbox example.

For region-locked SKUs, fail before payment: GET /availability with the buyer country at product-page time (hide the buy button) → preview with the real buyer IP at cart → reserve or hold → then charge and commit. Geo failure at commit should be rare. See Territory enforcement.

1. Authenticate#

curl -s -X GET "https://api.avrix.io/api/seller/v1/whoami" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Confirm data.key.environment is sandbox, the required data.key.scopes are present, and read capabilities (for example checkoutHoldEnabled). To see whether the company can sell yet, call GET /integration/status and read readyToSell and each gate's hint (Which call answers what).

2. Catalog sync#

Snapshot (or paginated products) plus allocations — then merge to the sellable set:

Bash
curl -s "https://api.avrix.io/api/seller/v1/catalog/snapshot" \
  -H "Authorization: Bearer avrix_sk_sbx_your_key_here"

curl -s "https://api.avrix.io/api/seller/v1/allocations" \
  -H "Authorization: Bearer avrix_sk_sbx_your_key_here"

Keep only SKUs that have sellable: true on allocations, joined to the catalog on the SKU id (skuId on an allocation row, id on a sharedSkus[] entry); see Sellable SKU readiness. Persist SANDBOX-ALWAYS-001 when present.

Optional delta loop: keep the snapshot's meta.changesCursor, send it as cursor, apply the page, store meta.nextCursor when it is not null, and ask again at once while meta.hasMore is true. cursor is the position to keep; since (a time) is only for a first catch-up when you have no cursor yet. The rules are on Lists and pagination.

Bash
curl -s "https://api.avrix.io/api/seller/v1/catalog/changes?cursor=$CHANGES_CURSOR" \
  -H "Authorization: Bearer avrix_sk_sbx_your_key_here"

3. Availability#

curl -s -X GET "https://api.avrix.io/api/seller/v1/availability?skuCode=SANDBOX-ALWAYS-001&quantity=1&country=US" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Use this for commit-time accuracy. List expand fields are advisory. The example checks US; for this scenario send countryCode=NL.

4. Preview#

curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/preview" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "skuCode": "SANDBOX-ALWAYS-001",
  "quantity": 1,
  "countryCode": "NL",
  "orderReference": "store-order-10432",
  "integrationOrderContext": {
    "schemaVersion": 1,
    "salesCountryCode": "NL",
    "currencyCode": "EUR",
    "salesPriceGrossMinor": 7999,
    "priceIncludesTax": true,
    "salesTaxRatePercent": 21,
    "salesChannel": "web",
    "salesTaxAmountMinor": 1388
  }
}'

Gate: proceed only when canFulfill is true. Store unitPriceCents (example below uses 5999 for SANDBOX-ALWAYS-001).

5. Charge at your PSP#

Create and confirm the payment at your PSP for the retail amount (in this scenario 7999, EUR 79.99 including VAT: the salesPriceGrossMinor you declare in step 6). Your retail price is yours to set; the preview's unitPriceCents (5999) is the list price the sale is booked at, not a floor or a ceiling for it. Keep the PSP payment id for paymentProcessorReference.

Avrix is not in this transaction.

6. Create the order#

curl -s -X POST "https://api.avrix.io/api/seller/v1/orders" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Idempotency-Key: store-order-10432" \
  -H "Content-Type: application/json" \
  -d '{
  "skuCode": "SANDBOX-ALWAYS-001",
  "quantity": 1,
  "orderReference": "store-order-10432",
  "expectedUnitPriceCents": 5999,
  "countryCode": "NL",
  "deliveryMode": "key",
  "integrationOrderContext": {
    "schemaVersion": 1,
    "salesCountryCode": "NL",
    "currencyCode": "EUR",
    "salesPriceGrossMinor": 7999,
    "priceIncludesTax": true,
    "salesTaxRatePercent": 21,
    "salesChannel": "web",
    "salesTaxAmountMinor": 1388,
    "paymentProcessorReference": "pay_3QxK2mB9",
    "checkoutSessionId": "cs_sandbox_10432"
  }
}'

Persist data.keys[] (with matching keyIds[]) before responding to the buyer.

7. Webhook#

Register (once) and handle order.fulfilled:

curl -s -X POST "https://api.avrix.io/api/seller/v1/webhooks" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Idempotency-Key: webhook-create-1" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://store.example.com/avrix/webhooks",
  "events": [
    "order.fulfilled",
    "order.failed",
    "allocation.depleted"
  ]
}'

Verify X-Avrix-Signature. Dedupe on eventId. Expect no key plaintext in the payload.

8. Reconcile#

curl -s -X GET "https://api.avrix.io/api/seller/v1/orders?orderReference=store-order-10432" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Compare aggregates to your OMS. Schedule this even when webhooks succeed.


Failure paths#

Out of stock after charge#

POST /orders → 409 NO_AVAILABLE_KEYS.

Action: Refund the buyer at your PSP. Do not retry with a new idempotency key hoping for stock.

Price changed#

422 CATALOG_PRICE_MISMATCH or WHOLESALE_PRICE_MISMATCH.

Action: Re-preview, decide whether to re-price or cancel the retail charge, then submit a corrected order (new payment / new idempotency key if the prior attempt never committed).

Duplicate request (same key, same body)#

200 with the original response (may include Idempotency-Replayed: true).

Action: Treat as success; do not pull again.

Duplicate request (same key, different body)#

409 IDEMPOTENCY_KEY_MISMATCH with details.requestBodyHash.

Action: Fix the client. Do not force a new key against the same payment.

Timeout after submit#

No HTTP response after POST /orders.

Action: Retry with the same Idempotency-Key and body. If still unclear, GET /orders?orderReference=store-order-10432. Never open a second order for the same charge.

Duplicate webhook#

Same logical fulfilment delivered twice with different or repeated attempts.

Action: Dedupe on eventId. Side effects must be idempotent.

Unauthorized SKU#

404 / contract errors when the SKU is not shared or not sellable to you.

Action: Re-sync catalog + allocations. Do not hard-code SKUs outside your sellable set.


What links here

Published guides that link to this page.

Search docs

Search documentation…