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.
| Field | Value |
|---|---|
| API key | avrix_sk_sbx_your_key_here |
| SKU | SANDBOX-ALWAYS-001 |
orderReference | store-order-10432 |
| Buyer country | NL |
| Currency | EUR |
| Retail price you charge | 7999 (EUR 79.99, including 21% VAT of 1388) |
| Base URL | https://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:
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.
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.