Creating 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.

• An active 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

Scope: seller:keys:pull

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.

Use Order context as the field authority. Production keys enforce the full commercial-evidence set (net, tax, payment method family, PSP reference, checkout session, buyer IP, and country) — sandbox does not. An integration that passes in sandbox can return 422 in production for missing evidence.

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",
    "consumerIp": "198.51.100.42"
  }
}'

For a production-shaped body with all required evidence fields, see Order context.

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",
    "orderReadableId": "ord_01J8XYZ...",
    "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"
  }
}

When immediateFulfilment is false (or the platform defers reveal), the body includes deferredReveal: true and keys: [] while still reporting pulled and keyIds when available. Retrieve codes through your recovery / export workflows — do not assume plaintext will appear later on GET /orders.

1. POST /orders/preview — gate on canFulfill: true; store unitPriceCents.
2. Optional: POST /orders/hold when checkout hold is enabled.
3. Charge the buyer at your PSP.
4. POST /orders with stable Idempotency-Key, orderReference, and expectedUnitPriceCents.
5. Persist entitlements (keys + keyIds) from the response before acknowledging the buyer UI.
6. Handle order.fulfilled for ops correlation (no key plaintext on the webhook wire).

When one buyer cart spans multiple SKUs, use POST /api/seller/v1/orders/bulk instead of multiple independent POST /orders calls. Each line still needs sellability (allocation + territory) and a stable idempotency strategy — see OpenAPI for the line-item body shape.

Prefer one logical cart → one bulk request with a cart-level idempotency key (or documented per-line keys) so retries do not double-fulfil. For single-SKU checkout, stay on POST /orders.

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: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.

• Order lifecycle
• Order context
• Checkout holds
• Fulfilment and keys
• Idempotency