Creating orders

POST /orders fields, safe creation pattern, and unknown-outcome recovery.

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#

SituationCall this endpoint?
Buyer paid, preview confirmed fulfilabilityYes
Buyer has not paid yetNo — preview only
Preview returned canFulfill: falseNo — it will fail
You want to show a priceNo — use POST /orders/preview
High-contention drop needing guaranteed capacityUse reserve then commit (Hot drop)
More than one SKU in a single transactionUse POST /orders/bulk

Prerequisites#

  • An active Business Model Agreement (BMA) with the vendor
  • An allocation covering the SKU with sellable: true on 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#

HeaderRequiredNotes
AuthorizationYesBearer avrix_sk_sbx_your_key_here
Content-TypeYesapplication/json
Idempotency-KeyYesStable per logical order. Honoured for 24 hours.
X-Request-IdNoYour correlation id. Echoed in responses and errors.

Request body#

FieldTypeRequiredDescription
skuIdstring (uuid)One ofProvide either skuId or skuCode, not both
skuCodestringOne ofHuman-readable SKU code
quantityintegerYes1–1000. All-or-nothing
orderReferencestringYesYour immutable business identifier (max 255)
expectedUnitPriceCentsintegerUsuallyCanonical price echo — unitPriceCents from preview (see pricing note)
expectedWholesaleUnitPriceCentsintegerNoDeprecated alias of the price echo (removal planned for v2); if both price fields are sent they must be equal
countryCodestringRecommendedISO 3166-1 alpha-2 (e.g. US). Promoted into IOC when absent
deliveryModestringNokey (default) — plaintext codes in the response
checkoutHoldIdstring (uuid)NoBind to an active checkout hold
priceCommitmentTokenstringNoSigned price binding from preview, when issued
customerReferencestringNoYour customer / account reference
metadataobjectNoOpaque partner metadata
backorderOnUnavailablebooleanNoRecommended 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
immediateFulfilmentbooleanNoWhen false, keys are assigned but plaintext is omitted (deferredReveal: true, keys: [])
integrationOrderContextobjectYes in productionCommercial 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:

JSON
{
  "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:

JSON
{
  "skuCode": "GAME-STD",
  "quantity": 1,
  "orderReference": "store-order-10432",
  "priceCommitmentToken": "pct1.…",
  "integrationOrderContext": { "consumerIp": "198.51.100.42" }
}

Avrix fills in the rest:

FieldFilled from
salesChannel, paymentMethodFamily, priceIncludesTaxyour presets (priceIncludesTax: null follows the VAT rate of the buyer's country)
checkoutSessionIdyour orderReference
salesCountryCodethe buyer IP, else the price commitment, else storeCountryCode
currencyCode, salesPriceGrossMinor, salesPriceNetMinor, salesTaxAmountMinorthe price commitment × quantity, split with the tax rate
salesTaxRatePercentthe VAT rate in force for the sale country (not for countries with regional sales tax, such as the US: send your rate)
schemaVersion1

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.

JSON
{
  "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.

  1. POST /orders/preview — gate on canFulfill: true; store unitPriceCents.
  2. Optional in every profile: POST /orders/hold when GET /whoami reports capabilities.checkoutHoldEnabled: true and your payment page can take long enough for stock to move (see Checkout holds).
  3. Charge the buyer at your PSP.
  4. POST /orders with stable Idempotency-Key, orderReference, and expectedUnitPriceCents.
  5. Persist entitlements (keys + keyIds) and orderId from the response before acknowledging the buyer UI.
  6. Handle order.fulfilled for 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:

  1. Retry the same Idempotency-Key and body.
  2. If still unclear, GET /api/seller/v1/orders?orderReference=store-order-10432 (status only — never key plaintext).
  3. If the aggregate says fulfilled but you never stored the keys (you crashed between the pull and your own database write), call POST /api/seller/v1/orders/recover-keys with the same orderReference (scope seller:orders:write, or the legacy seller:keys:pull). It returns the live keys and keyIds already sold under that reference, never pulls new inventory, and is audited as a reveal. Re-posting POST /orders with the same reference and quantity replays the same keys as well.
  4. 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.
  5. 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#

StatusMeaning
200Order committed
400Malformed request / missing idempotency key / some billing failures
401Invalid or wrong-environment key
402Payment not cleared (PAYMENT_NOT_CLEARED) — refund the buyer
403Missing scope, IP not allowed, contract inactive, or capability disabled
404SKU not visible or PRODUCT_NOT_SELLABLE — branch on code, not status alone
409Insufficient vendor stock (NO_AVAILABLE_KEYS), allocation cap reached (ALLOCATION_EXCEEDED), price mismatch, or idempotency conflict / in-flight
410Hot-drop reservation gone (when using reserve/commit)
412Checkout-hold precondition failed
422Validation, territory, or commercial-evidence failure
429Rate limited — honour Retry-After
503Temporary failure — safe to retry with the same key
504Hot-path timeout (HOT_PATH_TIMEOUT) — retry-safe; pull did not commit

Common mistakes#

MistakeFix
Fresh Idempotency-Key per retryMint once per logical order
Not persisting keys and keyIds immediatelyWrite both to your vault before buyer response
Expecting keys[] objects with keyIdKeys are plaintext strings; UUIDs are in keyIds[]
Sending deliveryMode: "keys"Use "key" or omit (default)
Reusing orderReference across different ordersOne business order → one reference
Sending wholesale cost as salesPriceGrossMinorThat field is retail gross
Sending only what a sandbox key requiresProduction requires the full evidence set — see Order context
Calling without a recent previewRe-preview when price or stock may have drifted
Retrying 422 unchangedDeterministic — fix the request

What links here

Published guides that link to this page.

Search docs

Search documentation…