Hot-drop reserve & commit

High-throughput reserve and commit for vendor-declared launches.

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 sends allocation.updated with reason: 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#

Diagram

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

JSON
{
  "data": {
    "type": "reservation",
    "reservationId": "f9f7e2c8-...",
    "allocationId": "...",
    "quantity": 1,
    "expiresAt": "2026-08-05T18:21:00.000Z",
    "expiresInSeconds": 60,
    "remainingSlots": 14987,
    "orderReference": "store-order-10432"
  }
}
StatusCodeWhen
404NOT_FOUNDNo active allocation for your seller
403FORBIDDENAllocation paused or revoked
412HOT_DROP_NOT_ENABLEDAllocation not in hot-drop mode — use POST /orders
409SOLD_OUTNo remaining slots
422QUANTITY_INVALIDQuantity must be a positive integer
503STORE_UNAVAILABLECoordination 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).

Bash
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).

StatusCodeWhen
410RESERVATION_GONEExpired, unknown, or already consumed — re-reserve
409ALLOCATION_NOT_AVAILABLEAllocation 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/reserve on non-hot-drop allocations (412 every time). Read hotDropMode on GET /allocations, and go back to POST /orders when allocation.updated reports it off.
  • Calling /orders/commit without a prior reserve — use POST /orders instead.
  • Polling reserve to “warm” counters — burns write budget.
  • Treating remaining slots as a storefront stock badge — use GET /availability for display.

What links here

Published guides that link to this page.

Search docs

Search documentation…