Checkout holds

Create, read and release checkout holds that keep keys for a buyer while they pay.

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#

Diagram

Holds do not pull keys. Authority remains the order commit path.

When to use#

  1. POST /api/seller/v1/orders/preview — gate on canFulfill (do not charge if false).
  2. POST /api/seller/v1/orders/hold (optional in every profile, available when GET /whoami reports capabilities.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). Send countryCode (required for API allocations) and the same integrationOrderContext you 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.
  3. Charge the buyer at your PSP.
  4. POST /api/seller/v1/orders with the same SKU, quantity, orderReference, and optional checkoutHoldId.

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

FieldMeaning
holdId / checkoutHoldIdThe same id under both names. Pass it on POST /orders as checkoutHoldId (holdId is accepted there too)
expiresAt / expiresInSecondsWhen the hold ends, and the seconds left until then
allocationId, skuId, skuCode, quantity, orderReferenceWhat the hold covers
maxFulfillableQuantity, remainingSlotsCeiling observed at hold time, and the hold capacity left after this hold
unitPriceCents, currencyCode, currencyExponent, salesCountryCode, priceBoundAtAPI 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, advertisedUnitPriceCentsHow 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.missingThe 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:

Bash
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 holdHot-drop reserve
Requires hot-drop modeNoYes
Commit pathPOST /ordersPOST /orders/commit
Typical TTLMinutesAbout 60 seconds
When to useOrdinary checkout racesDeclared launches above ~500 RPS

What links here

Published guides that link to this page.

Search docs

Search documentation…