POST /api/seller/v1/orders
Commits a sale and issues entitlements. This is the endpoint that consumes allocation capacity and records a wholesale sale for settlement.
Call it after you have charged the buyer at your PSP and after POST /orders/preview returned canFulfill: true.
When to call it#
| Situation | Call this endpoint? |
|---|---|
| Buyer paid, preview confirmed fulfilability | Yes |
| Buyer has not paid yet | No — preview only |
Preview returned canFulfill: false | No — it will fail |
| You want to show a price | No — use POST /orders/preview |
| High-contention drop needing guaranteed capacity | Use reserve then commit (Hot drop) |
| More than one SKU in a single transaction | Use POST /orders/bulk |
Prerequisites#
- An active Business Model Agreement (BMA) with the vendor
- An allocation covering the SKU with
sellable: trueon GET /allocations - A territory catalog price for the buyer’s country (API business model)
- A completed payment at your PSP
- A recent preview for the same SKU, quantity, and country
Authorisation#
Scope: seller:keys:pull
Request headers#
| Header | Required | Notes |
|---|---|---|
Authorization | Yes | Bearer avrix_sk_sbx_your_key_here |
Content-Type | Yes | application/json |
Idempotency-Key | Yes | Stable per logical order. Honoured for 24 hours. |
X-Request-Id | No | Your correlation id. Echoed in responses and errors. |
Request body#
| Field | Type | Required | Description |
|---|---|---|---|
skuId | string (uuid) | One of | Provide either skuId or skuCode, not both |
skuCode | string | One of | Human-readable SKU code |
quantity | integer | Yes | 1–1000. All-or-nothing |
orderReference | string | Yes | Your immutable business identifier (max 255) |
expectedUnitPriceCents | integer | Usually | Canonical price echo — unitPriceCents from preview (see pricing note) |
expectedWholesaleUnitPriceCents | integer | No | Deprecated alias of the price echo (removal planned for v2); if both price fields are sent they must be equal |
countryCode | string | Recommended | ISO 3166-1 alpha-2 (e.g. US). Promoted into IOC when absent |
deliveryMode | string | No | key (default) — plaintext codes in the response |
checkoutHoldId | string (uuid) | No | Bind to an active checkout hold |
priceCommitmentToken | string | No | Signed price binding from preview, when issued |
customerReference | string | No | Your customer / account reference |
metadata | object | No | Opaque partner metadata |
backorderOnUnavailable | boolean | No | Recommended once the buyer has paid. When stock runs out (NO_AVAILABLE_KEYS), the order becomes a customer-order backorder (status: awaiting_stock, backorderExpiresAt) instead of a 409. On by default (GET /whoami capabilities.backorderEnabled); 403 BACKORDER_NOT_ALLOWED when the Content Owner opted out. The order waits for order.ready, then POST /orders/{orderId}/fulfill. Still unfulfilled at backorderExpiresAt (default 14 days), it is cancelled with order.backorder_expired: refund the buyer |
immediateFulfilment | boolean | No | When false, keys are assigned but plaintext is omitted (deferredReveal: true, keys: []) |
integrationOrderContext | object | Yes in production | Commercial evidence for the retail transaction |
Pricing note. Send expectedUnitPriceCents equal to preview’s unitPriceCents. A priceCommitmentToken can satisfy the echo when present. Complimentary-model allocations may waive the echo. Omitting a required echo returns EXPECTED_UNIT_PRICE_REQUIRED.
Price vocabulary (one meaning per name). expectedUnitPriceCents is the only commit-time
price field going forward — expectedWholesaleUnitPriceCents is a deprecated alias that will be
removed in v2. pricePerKeyCents (on GET /allocations rows) is an advisory wholesale-cost
summary from the grant — never send it on a commit, and never confuse it with the catalog list
price that preview returns under the API business model, where it is always null.
integrationOrderContext#
Use Order context as the field authority. Every key, sandbox
included, must declare schemaVersion, salesCountryCode (or the top-level countryCode),
salesPriceGrossMinor, salesTaxRatePercent and salesChannel. Production keys also enforce the
commercial evidence (currency, net, tax amount, payment method family, PSP reference, checkout
session, buyer IP); sandbox keys do not. An integration that sends only the sandbox set passes in
sandbox and returns 422 in production, so send the full set from the start.
Order presets: send only the essentials#
Save your store's defaults once with PUT /me/integration-presets (scope seller:account:manage) or in the console under Settings → Commercial → Order presets:
{
"salesChannel": "web",
"paymentMethodFamily": "card",
"priceIncludesTax": null,
"storeCountryCode": "NL",
"deriveAmounts": true
}
A production order then needs only the SKU, quantity, orderReference, the buyer IP and the priceCommitmentToken from the preview:
{
"skuCode": "GAME-STD",
"quantity": 1,
"orderReference": "store-order-10432",
"priceCommitmentToken": "pct1.…",
"integrationOrderContext": { "consumerIp": "198.51.100.42" }
}
Avrix fills in the rest:
| Field | Filled from |
|---|---|
salesChannel, paymentMethodFamily, priceIncludesTax | your presets (priceIncludesTax: null follows the VAT rate of the buyer's country) |
checkoutSessionId | your orderReference |
salesCountryCode | the buyer IP, else the price commitment, else storeCountryCode |
currencyCode, salesPriceGrossMinor, salesPriceNetMinor, salesTaxAmountMinor | the price commitment × quantity, split with the tax rate |
salesTaxRatePercent | the VAT rate in force for the sale country (not for countries with regional sales tax, such as the US: send your rate) |
schemaVersion | 1 |
Anything you send wins over the presets. Each filled field is recorded as a preset or derived value (declarationProvenance) on the delivery and sale records, so finance can tell what your store declared from what Avrix filled in. With presets, paymentProcessorReference is recommended rather than required. GET /whoami lists only what is still required (requiredDeclarationsByOperation) and shows integrationPresets. DELETE /me/integration-presets goes back to the full declaration.
Example request (sandbox)#
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"
}
}'For a production-shaped body with all required evidence fields, see Order context.
Success response — 200#
Plaintext keys are a string array. Key UUIDs for refunds and returns are in a separate top-level keyIds array (keys[i] corresponds to keyIds[i]).
activation is the guaranteed activation set for the SKU (worldwide, region_locked with countries, or unknown) — the same object as GET /allocations and preview lines — so you can show "activates in" at delivery without a second lookup. It is the intersection across the SKU's inventory batches, not the specific batch this key came from. See Territory enforcement.
{
"data": {
"type": "fulfilled",
"skuId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"skuCode": "SANDBOX-ALWAYS-001",
"orderReference": "store-order-10432",
"fulfillmentState": "fulfilled",
"orderId": "ord_6rfz4y3b",
"orderReadableId": "ord_6rfz4y3b",
"pulled": 1,
"keys": ["AAAA-BBBB-CCCC-DDDD"],
"keyIds": ["8f21a9b0-1234-5678-9abc-def012345678"],
"allocationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"activation": { "type": "region_locked", "countries": ["DE", "AT", "CH"] },
"transactionIds": ["c3d4e5f6-a7b8-9012-cdef-123456789012"],
"fulfilledAt": "2026-08-05T09:14:22.108Z"
}
}
Which id to store: orderId (ord_ plus eight characters) and your own orderReference.
orderId is the order's one id: the same value on GET /orders, GET /orders/{orderId}, bulk
lines and the order.fulfilled webhook, and every endpoint that addresses an order accepts it.
orderReadableId is a deprecated alias; on contract date 2026-12-01 and later it always equals
orderId. To look an order up later, call GET /orders/{orderId} or
GET /orders?orderReference=….
What it cost: on an API-model (revenue share) allocation the response also carries economics:
the billed unit and total price, any settlement promo, the Content Owner's share, your share, the
platform fee and the VAT deducted, summed from the order's sale rows (transactionIds). It is
null on a wholesale or complimentary allocation, which is billed per allocation.
Deferred reveal#
When immediateFulfilment is false, the keys are sold and assigned to the order but not
revealed: the body has deferredReveal: true and keys: [], with pulled and keyIds. Read the
keys when you need them with POST /orders/recover-keys and the order's orderReference. That call
reveals the keys already sold under the reference, never pulls new ones, and is recorded as a
reveal; see Fulfilment and keys for the request and the
answer. GET /orders never returns plaintext, and POST /keys/export would sell you new keys
rather than reveal these.
Safe order creation pattern#
This is the default checkout flow for every storefront. A checkout hold and hot-drop reserve/commit are additions, never replacements. Stock and reservations compares them and explains the stock numbers.
POST /orders/preview— gate oncanFulfill: true; storeunitPriceCents.- Optional in every profile:
POST /orders/holdwhenGET /whoamireportscapabilities.checkoutHoldEnabled: trueand your payment page can take long enough for stock to move (see Checkout holds). - Charge the buyer at your PSP.
POST /orderswith stableIdempotency-Key,orderReference, andexpectedUnitPriceCents.- Persist entitlements (
keys+keyIds) andorderIdfrom the response before acknowledging the buyer UI. - Handle
order.fulfilledfor ops correlation (no key plaintext on the webhook wire).
Bulk orders#
When one buyer cart spans several SKUs, send it as one POST /orders/bulk request instead of
several POST /orders calls. Each line is its own order, and strict decides whether the cart is
all or nothing. Bulk orders has the request, a sandbox example, the strict and
non-strict answers (including rolled_back and rollback_incomplete) and the retry rules. For a
single SKU, stay on POST /orders.
Unknown outcome recovery#
If the HTTP call times out after you charged the buyer:
- Retry the same
Idempotency-Keyand body. - If still unclear,
GET /api/seller/v1/orders?orderReference=store-order-10432(status only — never key plaintext). - If the aggregate says
fulfilledbut you never stored the keys (you crashed between the pull and your own database write), callPOST /api/seller/v1/orders/recover-keyswith the sameorderReference(scopeseller:orders:write, or the legacyseller:keys:pull). It returns the live keys andkeyIdsalready sold under that reference, never pulls new inventory, and is audited as a reveal. Re-postingPOST /orderswith the same reference and quantity replays the same keys as well. - If no aggregate exists and retries keep failing, escalate with
X-Request-Id— do not open a second order with a new key against the same payment. - If Avrix returns
NO_AVAILABLE_KEYS(or wallet/KYB 402 after charge), refund at your PSP. Avrix does not auto-refund.
See Idempotency and Order lifecycle.
Common status codes#
| Status | Meaning |
|---|---|
200 | Order committed |
400 | Malformed request / missing idempotency key / some billing failures |
401 | Invalid or wrong-environment key |
402 | Payment not cleared (PAYMENT_NOT_CLEARED) — refund the buyer |
403 | Missing scope, IP not allowed, contract inactive, or capability disabled |
404 | SKU not visible or PRODUCT_NOT_SELLABLE — branch on code, not status alone |
409 | Insufficient vendor stock (NO_AVAILABLE_KEYS), allocation cap reached (ALLOCATION_EXCEEDED), price mismatch, or idempotency conflict / in-flight |
410 | Hot-drop reservation gone (when using reserve/commit) |
412 | Checkout-hold precondition failed |
422 | Validation, territory, or commercial-evidence failure |
429 | Rate limited — honour Retry-After |
503 | Temporary failure — safe to retry with the same key |
504 | Hot-path timeout (HOT_PATH_TIMEOUT) — retry-safe; pull did not commit |
Common mistakes#
| Mistake | Fix |
|---|---|
Fresh Idempotency-Key per retry | Mint once per logical order |
Not persisting keys and keyIds immediately | Write both to your vault before buyer response |
Expecting keys[] objects with keyId | Keys are plaintext strings; UUIDs are in keyIds[] |
Sending deliveryMode: "keys" | Use "key" or omit (default) |
Reusing orderReference across different orders | One business order → one reference |
Sending wholesale cost as salesPriceGrossMinor | That field is retail gross |
| Sending only what a sandbox key requires | Production requires the full evidence set — see Order context |
| Calling without a recent preview | Re-preview when price or stock may have drifted |
Retrying 422 unchanged | Deterministic — fix the request |