Order lifecycle

States, transitions, and recovery from preview to fulfillment.

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.

The golden path#

Diagram

Three rules govern the whole flow:

  1. Never charge before canFulfill: true. An order is all or nothing: Avrix delivers the whole quantity or none of it. Only a bulk cart can deliver some lines and refuse others (see Bulk orders).
  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.

States#

Checkout and fulfilment path:

Diagram

After fulfilment:

Diagram
StateMeaningTerminal
previewedPriced and checked. No commitment, no capacity held. Not a persisted order.No
heldCapacity and price provisionally reserved for a short TTL.No
reservedHot-drop capacity claimed, awaiting commit.No
preorderedKey-locked pre-order: the keys were reserved when the order was placed, and Avrix delivers them at the release date. Only pre-order lines of POST /orders/bulk (and of POST /keys/pull / POST /keys/export) are placed this way.No
awaiting_releasePre-order placed with POST /orders. No key is locked: the order counts against your allocation until inventory covers it.No
awaiting_stockBackorder placed with backorderOnUnavailable. No key is locked.No
readyInventory covers the order. Call POST /orders/{orderId}/fulfill to get the keys: nothing is delivered until you do.No
partially_fulfilledPart of the status vocabulary, but no order is set to it: every order is delivered in full or not at all.No
fulfilledEntitlements issued. Money is owed to Avrix.Yes
failedRejected at commit. No entitlement, no charge from Avrix.Yes
cancelledPre-order, backorder or ready order cancelled with POST /orders/cancel before fulfilment.Yes
returnedKeys returned via quarantine (not recycled into sellable inventory without review).Yes
refundedRefund recorded against a fulfilled sale.Yes

previewed, held and reserved are steps of your checkout and leave no order behind. Every other state is an order status you read on GET /orders; which of them the listing can filter on depends on the read model (below).

GET /orders response shape (verified)#

GET /api/seller/v1/orders?orderReference=… (or orderReadableId=…, which takes any order id) returns an aggregate, not a single status string. GET /orders/{orderId} returns the same aggregate for an order id. The aggregate's orderId is the order's one id (the same value the create response returned) in both read models, and economics says what a delivered API-model order was billed at (null for wholesale). GET /whoami capabilities.orderReadModel says which read model the environment uses (durable or reconstruction):

JSON
{
  "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": []
  }
}
FieldMeaning for reconciliation
statusReconstruction default: preordered, fulfilled, returned, or refunded. When durable-order reads are on: status comes from sales.orders (awaiting_release, awaiting_stock, ready, fulfilled, …). Lines may expose qtyRequested / qtyPending / qtyAssigned / qtyRevealed.
orderIdThe order's one id, the value to store; the same in both read models and in the create response.
economicsWhat the delivered keys were billed at (API-model allocations), summed from the order's sale rows; null for wholesale or before delivery.
fulfilled[]Key pulls already completed for this orderReference (quantities and allocation ids). No key plaintext.
preOrderActive[]Active pre-order reservations still waiting for release.
refunds[]Refund/chargeback/return records against this reference: { refundId, status, keyIds }.
Both lines empty / 404No pulls or reservations for that reference — treat as not committed (or wrong lookup).

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

Filtering the listing by status. GET /orders?status= (no orderReference) filters the order listing. Which values it can serve depends on the read model of the environment:

Read modelstatus values the listing serves
Reconstruction (the default until durable-order reads are switched on)fulfilled, returned, refunded. The listing is built from delivered keys, so an order without a delivered key is not in it.
Durable-order readsEvery value: awaiting_release (and its earlier name preordered), awaiting_stock, ready, partially_fulfilled, fulfilled, cancelled, returned, refunded, failed.

On the reconstruction read model, a value from the second row that is not in the first cannot be served. What you get back depends on your contract date:

  • 2026-12-01 and later: 422 VALIDATION_FAILED. details.issues[0].field is status, the message names the value you sent, and details.issues[0].allowedValues lists the values the listing can serve.
  • Earlier dates and unpinned requests: 200 with an empty page (data: [], meta.nextCursor: null). An empty page here does not mean you have no such orders.

To read a preorder or a backorder that the listing cannot filter on, look it up by orderReference: the aggregate above reports preOrderActive[] on either read model.

Transitions and events#

TransitionTriggerWebhook
→ previewedPOST /orders/previewNone — preview is read-only
previewed → heldPOST /orders/holdNone
held → previewedDELETE /orders/hold or TTL expiryNone
previewed → reservedPOST /orders/reserve (hot-drop slot)None — the response carries reservationId and expiresAt
reserved → (released)The reservation's TTL runs out before POST /orders/commitNone — the slots return to the allocation
reserved → fulfilledPOST /orders/commitorder.fulfilled
previewed → fulfilledPOST /ordersorder.fulfilled
previewed → awaiting_releasePOST /orders on a pre_order SKU inside its pre-order window, when preorderEnabled is trueorder.reserved
previewed → awaiting_stockPOST /orders with backorderOnUnavailable when stock is out (on by default unless the Content Owner opted out)order.reserved
awaiting_stock → cancelledStill awaiting stock at backorderExpiresAt (default 14 days)order.backorder_expired
awaiting_stock → readyInventory covers the pending quantityorder.ready
awaiting_release → readyInventory covers the pending quantity and the release is deliverable: it is unlocked, or its pre-order window has closed and its release date has passed. Until then the order stays awaiting_release whatever the stock. A key-locked preordered order is never moved to ready: Avrix delivers it at the release.order.ready
ready → fulfilledPOST /orders/{orderId}/fulfillorder.fulfilled (and deprecated order.preorder_fulfilled when the order was a preorder)
previewed → preorderedA pre-order line of POST /orders/bulk (or POST /keys/pull, POST /keys/export): the keys are reserved at onceorder.reserved
preordered → fulfilledThe release date arrives and Avrix delivers the reserved keysorder.preorder_fulfilled, without keys: read them with POST /orders/recover-keys
(rejected)A preview, hold, reserve, commit or POST /orders call is refusedNone — the HTTP error is the answer and no order exists
preordered → not deliveredThe automatic delivery at release could not read the keysorder.failed (reason: preorder_fulfillment_decrypt_failed)
awaiting_release, awaiting_stock, ready, preordered → cancelledPOST /orders/cancelorder.cancelled (and its older name order.returned to endpoints that subscribe to it, with the same eventLogId)
fulfilled → returnedPOST /keys/returnorder.keys_returned
fulfilled → refundedPOST /refundsrefund.completed

Step by step#

1. Preview#

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.

2. Hold — optional#

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.

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

3. Charge the buyer#

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.

4. Create 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.

5. Deliver and persist#

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.

6. Reconcile#

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

Failure modes#

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

The order result is unknown#

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 and is fulfilled, the order succeeded and you need the keys: re-read them with POST /orders/recover-keys and the same orderReference. It returns the keys already sold under the reference and never pulls new inventory.
  3. If the order does not exist, it never committed. Retry from step 1 or refund the buyer.

The Key recovery runbook is the full procedure, including what recover-keys answers for returned, revoked and frozen keys.

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.

Inventory sold out between preview and order#

409 NO_AVAILABLE_KEYS. Avrix pulled nothing — the order is all-or-nothing, so there is no partial state to clean up. A key-locked pre-order line (bulk) follows the same rule: it reserves the whole quantity or nothing. A pre-order placed with POST /orders locks no key, so it is not refused for missing stock.

Send backorderOnUnavailable: true on every order placed after payment. Instead of the 409, the order is accepted as a customer-order backorder (status: awaiting_stock) against your allocation headroom, and the response carries backorderExpiresAt:

  1. Tell the buyer the key is on its way; keep the payment.
  2. On order.ready, call POST /orders/{orderId}/fulfill and deliver the keys.
  3. If stock has not arrived by backorderExpiresAt (default 14 days), Avrix cancels the order, releases the headroom and sends order.backorder_expired. Refund the buyer then.
  4. To give up earlier, cancel the order yourself and refund.

Backorders are on by default (whoami.capabilities.backorderEnabled). A Content Owner can opt its products out; those orders answer 403 BACKORDER_NOT_ALLOWED, and ALLOCATION_EXCEEDED is never backordered (new stock cannot fix a spent allocation).

Without a backorder 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.

Price changed between preview and order#

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.

Duplicate submission#

Handled by the idempotency layer.

SituationResult
Same key, identical bodyOriginal response replayed. No second fulfilment.
Same key, different bodyIDEMPOTENCY_KEY_MISMATCH with details.requestBodyHash
Same key, first request still runningIDEMPOTENCY_REQUEST_IN_FLIGHT with Retry-After
Idempotency store unavailableIDEMPOTENCY_STORE_UNAVAILABLE — rejected rather than risk a duplicate

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

Product not sellable#

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 rejected#

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.

Webhook arrives before the HTTP response#

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.

Duplicate or out-of-order webhooks#

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

Missed webhooks#

An endpoint outage past the retry schedule means lost deliveries. Recover by polling GET /orders?orderReference=… for each open order and reconciling, by replaying deliveries from the Console, and, on contract date 2026-12-01 and later, by reading GET /events (every event of the last 30 days, with eventType=order.cancelled,order.ready,… to narrow it). Do not depend on webhooks as your only source of truth for money-relevant state.

Preorders#

A pre-order SKU accepts orders before its release date. 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 applies at every commercial stage — preview, hold, reserve, commit, and bulk — so a rejection surfaces before the buyer pays, not after.

How the keys reach you depends on the call that placed the order. There are two models, and an order is always in exactly one of them:

Placed with POST /ordersA pre-order line of POST /orders/bulk
Responsetype: "pre-order", status: "awaiting_release", reserved, orderId; no keysLine type: "pre-order", reserved, releaseDate; no keys
Keys locked when you orderNo. The order counts against your allocation until inventory covers itYes. The keys are reserved for the order at once
Status on GET /ordersawaiting_release, then readypreordered
Keys are deliveredWhen you call POST /orders/{orderId}/fulfill after order.readyAutomatically, when the release date arrives
Webhooksorder.reserved, order.ready, order.fulfilledorder.reserved, order.preorder_fulfilled
Reading the keysThe fulfill response carries keys and keyIdsPOST /orders/recover-keys with the orderReference

POST /keys/pull and POST /keys/export place pre-orders the key-locked way, like a bulk line.

Pre-orders placed with POST /orders#

  1. POST /orders answers 200 with type: "pre-order" and status: "awaiting_release", and order.reserved fires. Store the orderId. Tell the buyer the key comes at release.
  2. When the Content Owner's inventory covers the order, Avrix moves it to ready and sends order.ready (checked every 5 minutes). This does not wait for the release date: order.ready can arrive before it.
  3. Call POST /orders/{orderId}/fulfill with an Idempotency-Key. The response carries the keys and keyIds: persist them and deliver them. order.fulfilled fires, and so does the deprecated order.preorder_fulfilled; neither carries keys.
  4. 409 ORDER_NOT_READY means the keys are not there yet: wait for the next order.ready, then retry with the same Idempotency-Key.

Nothing in this model is delivered automatically. Until you call fulfill, the buyer has no key. A pre-order does not expire the way a backorder does; cancel it if you no longer want it.

Key-locked pre-orders (bulk)#

The keys are reserved when the line is accepted, and Avrix delivers them itself when the release date arrives. order.preorder_fulfilled then fires with the orderReference and pulled, but no keys: read them with POST /orders/recover-keys and the same orderReference, and deliver them. Do not call fulfill for these orders. If the delivery at release cannot read the keys, order.failed fires with reason: preorder_fulfillment_decrypt_failed; recover the keys the same way, and contact support if that fails too.

Cancelling a pre-order#

Cancel with POST /orders/cancel before delivery, in either model and also while the order is ready. This releases what the order holds and emits order.cancelled (endpoints subscribed to its older name order.returned receive that, with the same eventLogId; use a stable Idempotency-Key so retries do not double-emit). After delivery, use the refund and return path (order.keys_returned / refund.completed).

Between the order and the delivery 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.

Release-date slips#

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. Nothing changes in how the keys arrive. An order placed with POST /orders still waits for order.ready; a key-locked pre-order is delivered automatically at the new date, with order.preorder_fulfilled.
  4. If the slip is unacceptable to a buyer, cancel their order with POST /orders/cancel and refund at your PSP.

Reservation extend#

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

POST /api/seller/v1/orders/reservations/{reservationId}/extend

The path parameter is the reservation id. POST /api/seller/v1/orders/{orderId}/extend is the older path of the same call: its orderId is that reservation id, not an order id. Both keep working.

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.

Refunds and returns#

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

Then declare the refund to Avrix with POST /refunds, using the same orderReference and the keyIds of the refunded keys. This is what moves the keys out of sellable stock and takes the sale out of what you owe:

curl -s -X POST "https://api.avrix.io/api/seller/v1/refunds" \
  -H "Authorization: Bearer $AVRIX_API_KEY" \
  -H "Idempotency-Key: refund-store-10432" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "refund",
  "refundReference": "re_store_10432",
  "orderReference": "store-order-10432",
  "keyIds": [
    "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
  ]
}'

For keys sold under the API model, the response lists one refund record per key under refunds[]; refunds[].id is the id GET /refunds/{refundId} reads, and GET /refunds?refundReference= finds them all again. Persist the keyIds from the original POST /orders response with your order line. If you did not, GET /orders/{orderId} lists them again.

Check first with POST /refunds/preview when a key may be outside the refund window. Chargebacks, dispute freezes, return requests to the Content Owner and the older POST /keys/return are covered in Refunds, chargebacks and returns.

What links here

Published guides that link to this page.

Search docs

Search documentation…