Two-step fulfilment for vendor-declared launch windows where peak demand on a single allocation exceeds what a single POST /orders round-trip should absorb (roughly >500 RPS sustained).
For ordinary catalog browsing and steady-state checkout, keep using POST /api/seller/v1/orders. Reserve + commit is two HTTP round-trips and adds latency. Hot drop is Profile C in Store integration profiles: only for allocations the vendor put in hot-drop mode, on top of the Profile B golden path.
When to use#
Use reserve/commit only when all of these are true:
- The Content Owner has switched the allocation to launch mode: GET /allocations shows
hotDropMode: true, and every switch sendsallocation.updatedwithreason: hot_drop_mode_changed. Launch mode is usually on for the launch days only. - You are integrating a declared launch (major drop, timed release, high-contention SKU).
- You expect contention above ~500 reserve RPS on that SKU.
- You can release or let TTL expire if the buyer abandons checkout.
Below that threshold, direct POST /orders is usually faster end-to-end.
Flow#
If the buyer abandons, the reservation expires (about 60 seconds). Explicit cancel/release is friendlier to other shoppers when your flow supports it.
POST /api/seller/v1/orders/reserve#
Requires Idempotency-Key. API-model allocations also run territory and consumer-geo
gates (same CONSUMER_* / TERRITORY_* codes as preview). Send countryCode and, under
enforcement, integrationOrderContext.consumerIp before you charge. See
Territory enforcement.
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/reserve" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: reserve-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 (200):
{
"data": {
"type": "reservation",
"reservationId": "f9f7e2c8-...",
"allocationId": "...",
"quantity": 1,
"expiresAt": "2026-08-05T18:21:00.000Z",
"expiresInSeconds": 60,
"remainingSlots": 14987,
"orderReference": "store-order-10432"
}
}
| Status | Code | When |
|---|---|---|
404 | NOT_FOUND | No active allocation for your seller |
403 | FORBIDDEN | Allocation paused or revoked |
412 | HOT_DROP_NOT_ENABLED | Allocation not in hot-drop mode — use POST /orders |
409 | SOLD_OUT | No remaining slots |
422 | QUANTITY_INVALID | Quantity must be a positive integer |
503 | STORE_UNAVAILABLE | Coordination store down — backoff; direct /orders may be acceptable |
POST /api/seller/v1/orders/commit#
Requires Idempotency-Key.
POST /api/seller/v1/orders/reservations/{reservationId}/commit is the same commit with the
reservation named in the path: send the same body without reservationId (or with the same one; a
different one is refused with 422 VALIDATION_FAILED). It runs the same handler and answers the
same way, and POST /orders/commit keeps working. Extend a reservation with
POST /api/seller/v1/orders/reservations/{reservationId}/extend
(Order lifecycle).
curl -s -X POST "https://api.avrix.io/api/seller/v1/orders/commit" \
-H "Authorization: Bearer avrix_sk_sbx_your_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commit-store-order-10432" \
-d '{
"reservationId": "f9f7e2c8-...",
"integrationOrderContext": {
"schemaVersion": 1,
"salesCountryCode": "US",
"currencyCode": "USD",
"salesPriceGrossMinor": 1999,
"salesPriceNetMinor": 1999,
"priceIncludesTax": true,
"salesTaxAmountMinor": 0,
"salesTaxRatePercent": 0,
"salesChannel": "web",
"paymentMethodFamily": "card",
"paymentProcessorReference": "pay_3QxK2mB9",
"checkoutSessionId": "cs_store_10432",
"consumerIp": "198.51.100.42"
}
}'
Successful response matches POST /orders (type: "fulfilled" with keys, or preorder shape).
| Status | Code | When |
|---|---|---|
410 | RESERVATION_GONE | Expired, unknown, or already consumed — re-reserve |
409 | ALLOCATION_NOT_AVAILABLE | Allocation paused / hot-drop flipped off mid-flight |
If the commit response was lost, retry with the same Idempotency-Key and body: within 24 hours the stored response, keys included, is replayed. A retry with a new key, or after that window, answers 410 RESERVATION_GONE although the order exists: look it up with GET /orders?orderReference=… (the reference the reservation was made with), store its orderId, and take the keys from POST /orders/recover-keys.
Idempotency#
Both reserve and commit require Idempotency-Key. Retry network faults with the same key and body. See Idempotency.
Anti-patterns#
- Calling
/orders/reserveon non-hot-drop allocations (412every time). ReadhotDropModeonGET /allocations, and go back toPOST /orderswhenallocation.updatedreports it off. - Calling
/orders/commitwithout a prior reserve — usePOST /ordersinstead. - Polling reserve to “warm” counters — burns write budget.
- Treating remaining slots as a storefront stock badge — use
GET /availabilityfor display.
Related#
- Checkout holds — softer coordination for ordinary checkout
- Creating orders
- Order lifecycle