Short-lived capacity coordination between POST /orders/preview and POST /orders. Use holds to reduce preview→payment races without enabling hot-drop mode.
Checkout hold states#
Holds do not pull keys. Authority remains the order commit path.
When to use#
- POST /api/seller/v1/orders/preview — gate on
canFulfill(do not charge if false). POST /api/seller/v1/orders/hold(optional in every profile, available when GET /whoami reportscapabilities.checkoutHoldEnabled: true; the default flow is preview, charge, POST /orders) — reserve a slot for the checkout window (default 30 minutes, matching a hosted PSP page). SendcountryCode(required for API allocations) and the sameintegrationOrderContextyou will send to POST /orders (buyer IP,currencyCode,salesChannel): the hold runs the same order admission as preview and commit, so territory, footprint, currency, channel and consumer-geo refusals arrive before payment with the same codes (details.holdError) — a hold is never granted for a sale commit refuses for a reason you control.- Charge the buyer at your PSP.
- POST /api/seller/v1/orders with the same SKU, quantity,
orderReference, and optionalcheckoutHoldId.
Create a hold#
Check GET /whoami first: holds are available when capabilities.checkoutHoldEnabled is true.
A deployment without them answers 412 CHECKOUT_HOLD_DISABLED.
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/hold" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: hold-store-10432" \
-H "Content-Type: application/json" \
-d '{
"skuCode": "SANDBOX-ALWAYS-001",
"quantity": 1,
"countryCode": "NL",
"orderReference": "store-order-10432",
"integrationOrderContext": {
"schemaVersion": 1,
"salesCountryCode": "NL",
"currencyCode": "EUR",
"salesPriceGrossMinor": 7999,
"priceIncludesTax": true,
"salesTaxRatePercent": 21,
"salesChannel": "web",
"salesTaxAmountMinor": 1388
}
}'Successful response (data.type: checkout_hold):
| Field | Meaning |
|---|---|
holdId / checkoutHoldId | The same id under both names. Pass it on POST /orders as checkoutHoldId (holdId is accepted there too) |
expiresAt / expiresInSeconds | When the hold ends, and the seconds left until then |
allocationId, skuId, skuCode, quantity, orderReference | What the hold covers |
maxFulfillableQuantity, remainingSlots | Ceiling observed at hold time, and the hold capacity left after this hold |
unitPriceCents, currencyCode, currencyExponent, salesCountryCode, priceBoundAt | API allocations only: the unit price bound for the hold's lifetime, its currency and minor-unit digits, the country it was bound for, and when. Send unitPriceCents back as expectedUnitPriceCents on POST /orders |
initialUnitPriceCents, promo, promoResolution, listPromo, advertisedUnitPriceCents | How the bound price was reached: the list price before a settlement promotion, the promotion applied (if any), and the list-price promotion to advertise |
commitRequirements.missing | The integrationOrderContext fields POST /orders will still refuse without (payment-time fields: amounts, tax split, payment method, processor reference, checkout session) |
orderReference is required: one hold per cart, keyed by it. On a production key the buyer IP is
required too (integrationOrderContext.consumerIp or consumerGeoAttestId), as on POST /orders.
Common errors: 409 sold out, 404 SKU/allocation, 412 hold disabled, 422 a field the commit would refuse, or the agreement's geo-mismatch policy.
Replaying the create. POST /orders/hold is idempotent on its Idempotency-Key. A replay
answers the hold's live state: the same hold with its current expiresAt while it is live, and
404 HOLD_NOT_FOUND with details.holdState (released, consumed or expired) once it is
not. A released hold is never handed back as live; send a new Idempotency-Key to create a new
hold.
Holds are visible everywhere. Keys inside live holds are subtracted on GET /availability
(heldQuantity, sellableNow; maxFulfillableQuantity is net of holds), on POST /orders/preview
(canFulfill uses the net) and, advisorily, on GET /products?expand=availability and the catalog
snapshot. A hold is granted only up to what is in stock: the counter is clamped to
min(allocation headroom, inventory) − held on every request, so a hold never covers a key that is
not there.
One hold per cart. A second POST /orders/hold for an orderReference that a live hold
already covers is refused with 409 HOLD_EXISTS; details.holdId and details.expiresAt name
the hold to reuse (or release first). It takes no capacity.
GET /api/seller/v1/orders/hold/{holdId}#
Read a hold created with the same API key: what it holds, until when (expiresAt), and the price
it bound. A process that lost track of a hold reads it here instead of finding out at commit. Once
the hold is no longer live the read answers 404 HOLD_NOT_FOUND with details.holdState:
released or consumed while the hold store still remembers (24 hours), otherwise not_found
(expired, never existed, or created with another key). 503 STORE_UNAVAILABLE means the hold
store could not be read; retry after Retry-After. A lost holdId is recovered by replaying
POST /orders/hold with its original Idempotency-Key.
DELETE /api/seller/v1/orders/hold#
Requires Idempotency-Key. Idempotent: the response is 200 with data.released true when
this call freed the hold and false when it was already released, consumed or expired — the cart
is free either way, so retry freely. It never answers 404.
Release on cart abandon:
curl -s -X DELETE "https://api.avrix.io/api/seller/v1/orders/hold" \
-H "Authorization: Bearer avrix_sk_sbx_your_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: release-hold-store-order-10432" \
-d '{ "holdId": "<uuid>" }'
The same release names the hold in the path, with no body:
DELETE /api/seller/v1/orders/hold/{holdId}. It runs the same handler and answers the same way; a
body that also sends holdId must send the same one, or the request is refused with
422 VALIDATION_FAILED. DELETE /orders/hold with the body keeps working. See
Naming conventions.
Bind on create order#
Optional checkoutHoldId on POST /orders must match seller, SKU, quantity, and orderReference. The hold is consumed on successful pull.
TTL#
A hold lives 30 minutes by default, sized to a hosted PSP checkout. The lifetime is a platform
setting (between one minute and one hour): you cannot choose it per request, and a hold cannot be
extended. expiresAt on the create answer
(and on GET /orders/hold/{holdId}) is the time to trust. Expired holds release automatically;
prefer explicit DELETE on abandon so other shoppers see capacity sooner. If your checkout can
run longer than the hold, commit without it: a lapsed hold never blocks a paid order (below).
A lapsed hold never blocks a paid order. If POST /orders references a checkoutHoldId that has expired, been released, or been consumed, the commit proceeds as a plain order (inventory from the pool, price from priceCommitmentToken / expectedUnitPriceCents) and the response carries checkoutHold: { holdId, status: "expired", committedWithoutHold: true }. Only a hold that exists but does not match the body is rejected (422 HOLD_MISMATCH, recommended action fallback_to_post_orders_without_hold).
Revocation#
If the publisher revokes or pauses the allocation grant while holds are open, the platform
cancels those holds immediately (allocation.updated arrives with reason: "revoked" or
"paused"). A POST /orders carrying a cancelled checkoutHoldId fails hold validation — treat
it like an expired hold: re-preview, and if the SKU is no longer sellable, refund the buyer at
your PSP.
vs hot-drop#
| Checkout hold | Hot-drop reserve | |
|---|---|---|
| Requires hot-drop mode | No | Yes |
| Commit path | POST /orders | POST /orders/commit |
| Typical TTL | Minutes | About 60 seconds |
| When to use | Ordinary checkout races | Declared launches above ~500 RPS |