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.
When to use#
Use reserve/commit only when all of these are true:
- The vendor has enabled hot-drop mode on the allocation.
- 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.
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 |
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). - 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