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#
Three rules govern the whole flow:
- 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). - Always send a stable
Idempotency-Keyon writes. It is the only thing standing between a network blip and a double fulfilment. - Persist entitlements on first receipt. Key plaintext is returned once.
States#
Checkout and fulfilment path:
After fulfilment:
| State | Meaning | Terminal |
|---|---|---|
previewed | Priced and checked. No commitment, no capacity held. Not a persisted order. | No |
held | Capacity and price provisionally reserved for a short TTL. | No |
reserved | Hot-drop capacity claimed, awaiting commit. | No |
preordered | Key-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_release | Pre-order placed with POST /orders. No key is locked: the order counts against your allocation until inventory covers it. | No |
awaiting_stock | Backorder placed with backorderOnUnavailable. No key is locked. | No |
ready | Inventory covers the order. Call POST /orders/{orderId}/fulfill to get the keys: nothing is delivered until you do. | No |
partially_fulfilled | Part of the status vocabulary, but no order is set to it: every order is delivered in full or not at all. | No |
fulfilled | Entitlements issued. Money is owed to Avrix. | Yes |
failed | Rejected at commit. No entitlement, no charge from Avrix. | Yes |
cancelled | Pre-order, backorder or ready order cancelled with POST /orders/cancel before fulfilment. | Yes |
returned | Keys returned via quarantine (not recycled into sellable inventory without review). | Yes |
refunded | Refund 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):
{
"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": []
}
}
| Field | Meaning for reconciliation |
|---|---|
status | Reconstruction 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. |
orderId | The order's one id, the value to store; the same in both read models and in the create response. |
economics | What 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 / 404 | No 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 model | status 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 reads | Every 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-01and later:422 VALIDATION_FAILED.details.issues[0].fieldisstatus, the message names the value you sent, anddetails.issues[0].allowedValueslists the values the listing can serve.- Earlier dates and unpinned requests:
200with 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#
| Transition | Trigger | Webhook |
|---|---|---|
→ previewed | POST /orders/preview | None — preview is read-only |
previewed → held | POST /orders/hold | None |
held → previewed | DELETE /orders/hold or TTL expiry | None |
previewed → reserved | POST /orders/reserve (hot-drop slot) | None — the response carries reservationId and expiresAt |
reserved → (released) | The reservation's TTL runs out before POST /orders/commit | None — the slots return to the allocation |
reserved → fulfilled | POST /orders/commit | order.fulfilled |
previewed → fulfilled | POST /orders | order.fulfilled |
previewed → awaiting_release | POST /orders on a pre_order SKU inside its pre-order window, when preorderEnabled is true | order.reserved |
previewed → awaiting_stock | POST /orders with backorderOnUnavailable when stock is out (on by default unless the Content Owner opted out) | order.reserved |
awaiting_stock → cancelled | Still awaiting stock at backorderExpiresAt (default 14 days) | order.backorder_expired |
awaiting_stock → ready | Inventory covers the pending quantity | order.ready |
awaiting_release → ready | Inventory 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 → fulfilled | POST /orders/{orderId}/fulfill | order.fulfilled (and deprecated order.preorder_fulfilled when the order was a preorder) |
previewed → preordered | A pre-order line of POST /orders/bulk (or POST /keys/pull, POST /keys/export): the keys are reserved at once | order.reserved |
preordered → fulfilled | The release date arrives and Avrix delivers the reserved keys | order.preorder_fulfilled, without keys: read them with POST /orders/recover-keys |
| (rejected) | A preview, hold, reserve, commit or POST /orders call is refused | None — the HTTP error is the answer and no order exists |
preordered → not delivered | The automatic delivery at release could not read the keys | order.failed (reason: preorder_fulfillment_decrypt_failed) |
awaiting_release, awaiting_stock, ready, preordered → cancelled | POST /orders/cancel | order.cancelled (and its older name order.returned to endpoints that subscribe to it, with the same eventLogId) |
fulfilled → returned | POST /keys/return | order.keys_returned |
fulfilled → refunded | POST /refunds | refund.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.
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:
- 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. - 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 withPOST /orders/recover-keysand the sameorderReference. It returns the keys already sold under the reference and never pulls new inventory. - 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:
- Tell the buyer the key is on its way; keep the payment.
- On
order.ready, callPOST /orders/{orderId}/fulfilland deliver the keys. - If stock has not arrived by
backorderExpiresAt(default 14 days), Avrix cancels the order, releases the headroom and sendsorder.backorder_expired. Refund the buyer then. - 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.
| Situation | Result |
|---|---|
| Same key, identical body | Original response replayed. No second fulfilment. |
| Same key, different body | IDEMPOTENCY_KEY_MISMATCH with details.requestBodyHash |
| Same key, first request still running | IDEMPOTENCY_REQUEST_IN_FLIGHT with Retry-After |
| Idempotency store unavailable | IDEMPOTENCY_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 /orders | A pre-order line of POST /orders/bulk | |
|---|---|---|
| Response | type: "pre-order", status: "awaiting_release", reserved, orderId; no keys | Line type: "pre-order", reserved, releaseDate; no keys |
| Keys locked when you order | No. The order counts against your allocation until inventory covers it | Yes. The keys are reserved for the order at once |
Status on GET /orders | awaiting_release, then ready | preordered |
| Keys are delivered | When you call POST /orders/{orderId}/fulfill after order.ready | Automatically, when the release date arrives |
| Webhooks | order.reserved, order.ready, order.fulfilled | order.reserved, order.preorder_fulfilled |
| Reading the keys | The fulfill response carries keys and keyIds | POST /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#
POST /ordersanswers200withtype: "pre-order"andstatus: "awaiting_release", andorder.reservedfires. Store theorderId. Tell the buyer the key comes at release.- When the Content Owner's inventory covers the order, Avrix moves it to
readyand sendsorder.ready(checked every 5 minutes). This does not wait for the release date:order.readycan arrive before it. - Call
POST /orders/{orderId}/fulfillwith anIdempotency-Key. The response carries the keys andkeyIds: persist them and deliver them.order.fulfilledfires, and so does the deprecatedorder.preorder_fulfilled; neither carries keys. 409 ORDER_NOT_READYmeans the keys are not there yet: wait for the nextorder.ready, then retry with the sameIdempotency-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:
- Update the listing's release date from
newDate— do not wait for the next catalog sync. - Notify buyers with open pre-orders for the affected
skuIds(a slipped date is the single biggest source of pre-order support tickets). - Nothing changes in how the keys arrive. An order placed with
POST /ordersstill waits fororder.ready; a key-locked pre-order is delivered automatically at the new date, withorder.preorder_fulfilled. - If the slip is unacceptable to a buyer, cancel their order with
POST /orders/canceland 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.
Related#
- Integration recipes — the order call contract per flow
- Catalog and allocations — what is sellable
- Webhook guide — consuming lifecycle events
- Error reference — every code