Order lifecycle

Every Seller API order moves through a defined set of states. This page is the authoritative model: the states, the transitions, the webhook emitted at each one, and what to do when a transition fails. Other order pages describe individual endpoints; this page describes how they fit together.

Three rules govern the whole flow:

1. Never charge before canFulfill: true. Avrix does not partially fulfil.
2. Always send a stable Idempotency-Key on writes. It is the only thing standing between a network blip and a double fulfilment.
3. Persist entitlements on first receipt. Key plaintext is returned once.

Checkout and fulfilment path:

After fulfilment:

These labels describe the integration lifecycle (what your storefront should track). They are not a top-level status enum on GET /orders.

GET /api/seller/v1/orders?orderReference=… (or orderReadableId=…) returns an aggregate, not a single status string:

{
  "data": {
    "orderReference": "store-order-10432",
    "status": "fulfilled",
    "fulfilled": [
      {
        "skuCode": "EXAMPLE-WIN-US",
        "allocationId": "f8b1...",
        "fulfilledQuantity": 2,
        "firstKeyPullId": "…",
        "orderReadableId": "ord_…"
      }
    ],
    "preOrderActive": [
      {
        "skuCode": "EXAMPLE-PRE-US",
        "allocationId": "c410...",
        "reservedQuantity": 1,
        "reservedUntil": "2026-09-01T00:00:00.000Z"
      }
    ],
    "refunds": []
  }
}

States that leave no durable rows (previewed, held, reserved, failed, cancelled) cannot be reconstructed by lookup — a reference that never committed returns 404.

Call when the buyer reaches checkout. Preview is read-only, holds nothing, and is safe to retry.

Gate on canFulfill. If it is false, do not show a pay button — POST /orders will fail because Avrix never partially delivers.

Keep unitPriceCents. You must echo it as expectedUnitPriceCents on the order.

estimateOnly: true appears on every preview. Prices and availability reflect the moment of the call and can move. Do not persist a preview beyond the open cart.

For hot drops, slow checkouts, or multi-step flows where seconds matter, POST /orders/hold provisionally reserves capacity and binds the price for a short TTL.

curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/hold" \
  -H "Authorization: Bearer avrix_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold-store-order-10432" \
  -d '{
    "skuCode": "EXAMPLE-WIN-US",
    "quantity": 1,
    "countryCode": "US",
    "orderReference": "store-order-10432",
    "integrationOrderContext": {
      "schemaVersion": 1,
      "salesCountryCode": "US",
      "currencyCode": "USD",
      "salesPriceGrossMinor": 7999,
      "salesTaxRatePercent": 0,
      "salesChannel": "web"
    }
  }'

A hold carries the same settlement declarations as the order it precedes (gross price, tax rate, channel), so the bound snapshot is settled on the same basis; production keys also declare the buyer's IP. See Integration order context.

Idempotency-Key is required on both POST and DELETE /orders/hold.

While a hold is active, live catalog price drift is ignored — the bound snapshot is authoritative. Pass checkoutHoldId on POST /orders to use it. Release the hold with DELETE /orders/hold if the buyer abandons; otherwise it expires on its own.

Holds are capability-gated. Check capabilities.checkoutHoldEnabled on GET /whoami; when disabled, hold requests return CHECKOUT_HOLD_DISABLED and you should fall back to preview gating alone.

Entirely in your system, at your own PSP. Avrix has no visibility into this step and never charges or refunds your buyer.

Capture the payment reference — you send it as commercial evidence on the order.

This is the committing call. It consumes allocation capacity and issues entitlements.

Required: a stable Idempotency-Key, an orderReference, and expectedUnitPriceCents matching the preview. See Integration recipes for the full call contract and the interactive API reference for the request schema.

Write the entitlement to durable storage before returning a response to the buyer. Keys are returned once; GET /orders never returns plaintext. Persist keys[] with matching keyIds[] from the create-order response.

Confirm your record matches Avrix. GET /orders?orderReference=… is the lookup, and it is also your recovery path when anything goes wrong.

Implement all of these. Each is reachable in normal operation.

The most important failure mode in the integration. You charged the buyer and POST /orders timed out, returned a network error, or your process crashed before recording the response. You do not know whether keys were pulled.

Do this:

1. Retry the identical request — same Idempotency-Key, same body, byte for byte. If the original succeeded you receive the original response, including the original keys. If it never executed, it executes now. Either way you end with exactly one fulfilment.
2. If retries keep failing, look the order up: GET /orders?orderReference=store-order-10432. If it exists, the order succeeded and you need the entitlement — which you can no longer retrieve, so escalate to Avrix support with the order reference and request id.
3. If the order does not exist, it never committed. Retry from step 1 or refund the buyer.

Never do this:

• Do not charge the buyer again.
• Do not retry with a new idempotency key. That is a new order and will pull a second key.
• Do not assume failure from a timeout. A timeout is not an outcome.

409 NO_AVAILABLE_KEYS. Avrix pulled nothing — the order is all-or-nothing, so there is no partial state to clean up. Pre-order reservations follow the same rule: the reserved quantity must equal the requested quantity or the transaction releases every claim and fails.

backorderOnUnavailable: true does not create a zero-stock backorder today. Unless whoami.capabilities.backorderEnabled is true, that flag returns 403 FEATURE_DISABLED.

You have already charged the buyer. Refund at your PSP. Avrix will not do it and has no mechanism to. Then either offer an alternative SKU or apologise.

Prevent it by gating on canFulfill and, for high-contention drops, using a checkout hold or the reserve/commit flow.

CATALOG_PRICE_MISMATCH under the API business model (a legacy WHOLESALE_PRICE_MISMATCH code may still appear in the contract for non-API grants). Nothing was pulled and nothing was charged by Avrix.

Re-run preview to get the current price. Then decide, deliberately: if the new cost is higher than what you sold at, you may be selling at a loss. Do not blindly re-submit with the new price — this guard exists to force that decision rather than let it happen silently.

Prevent it with a checkout hold, which binds the price for its TTL.

Handled by the idempotency layer.

Keys are honoured for 24 hours. After that a replay is treated as a new request.

PRODUCT_NOT_SELLABLE. The product is not transactable: launchPhase is not available (including announced / pre_order), or it is discontinued / archived.

Your catalog is stale. Re-sync, delist the SKU, and refund if you charged.

TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, or SKU_REGION_UNRESOLVED. The buyer's country is not permitted for this SKU.

Gate earlier: check allowedCountries on product detail before offering the SKU to that market.

Possible and legal. order.fulfilled can reach your endpoint before POST /orders returns.

Design for it: key your webhook handler on orderReference, and make it tolerate an order it has not yet recorded — buffer it, or create the record from the webhook and reconcile when the HTTP response lands. Never assume an ordering relationship between the response and the event.

Delivery is at-least-once and not globally ordered. Deduplicate on X-Avrix-Event-Id and make handlers idempotent. See the webhook guide.

An endpoint outage past the retry schedule means lost events. Recover by polling GET /orders?orderReference=… for each open order and reconciling, and by replaying deliveries from the Console. Do not depend on webhooks as your only source of truth for money-relevant state.

A preorder SKU accepts orders before the release date. POST /orders returns a reservation rather than keys, and order.reserved fires. When the release date arrives Avrix fulfils automatically and order.preorder_fulfilled fires with the entitlement.

Acceptance is decided by the effective window, not the launch-phase label alone: with the capability on, an order is accepted only between preorderStart and preorderEnd (or once preorderUnlocked is set). Outside the window the order is rejected with PRODUCT_NOT_SELLABLE — never converted into a silent live pull. If the pre-order state cannot be verified at all, the API answers 503 PREORDER_STATE_UNAVAILABLE with Retry-After: 5; keys are never revealed on unverifiable state. The same gate now applies at every commercial stage — preview, hold, reserve, commit, and bulk — so a rejection surfaces before the buyer pays, not after.

Between those two events the buyer has paid and has no key. Communicate the release date clearly at checkout, and make sure your fulfilment pipeline handles delivery triggered by a webhook rather than by a synchronous response — this is the one flow where the entitlement genuinely arrives out of band.

Cancel with POST /orders/cancel before fulfilment — this releases pre-order reservations and emits order.returned (use a stable Idempotency-Key so retries do not double-emit). After fulfilment, use the refund and return path (order.keys_returned / refund.completed).

When a publisher moves a release date, Avrix emits release.date_changed with { productId, releaseId, skuIds, oldDate, newDate }. Playbook for stores holding pre-orders:

1. Update the listing's release date from newDate — do not wait for the next catalog sync.
2. Notify buyers with open pre-orders for the affected skuIds (a slipped date is the single biggest source of pre-order support tickets).
3. Re-check your pre-order window logic: fulfilment still happens automatically when the (new) release date arrives, and order.preorder_fulfilled fires then.
4. If the slip is unacceptable to a buyer, cancel their reservation with POST /orders/cancel and refund at your PSP.

Hot-drop and some reserved states support extending TTL before commit:

Use this when the buyer is still in checkout and the reservation would otherwise expire. Extend is only for reservation TTL — it does not re-issue keys.

You refund the buyer at your PSP. That is your decision and Avrix is not involved.

Separately, you may return the keys to Avrix inventory through quarantine, which is what affects settlement:

curl -s -X POST "https://api.avrix.io/api/seller/v1/keys/return" \
  -H "Authorization: Bearer avrix_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: return-store-order-10432" \
  -d '{
    "orderReference": "store-order-10432",
    "keyIds": ["k_8f21...", "k_9a02..."],
    "reason": "buyer_refund"
  }'

keyIds must come from the original POST /orders response or the order.fulfilled webhook. There is no endpoint that will give them to you later — another reason to persist the full fulfilment payload, not just the key strings.

Returned keys enter quarantine rather than going straight back to sellable inventory.

• Integration recipes — the order call contract per flow
• Catalog and allocations — what is sellable
• Webhook guide — consuming lifecycle events
• Error reference — every code