Stock & reservations

Checkout holds, launch reservations and launch windows side by side, the stock numbers, and the low-stock events.

Three different things in the Seller API set keys aside for your store, and the stock answers show more than one number. This page lines them up, so you can tell which one you are looking at and which one to use.

The default path#

Most stores need none of the reservations below. The default checkout is:

  1. POST /orders/preview: gate the Pay button on canFulfill.
  2. Charge the buyer.
  3. POST /orders with the same SKU, quantity and orderReference.

A paid order whose stock ran out in between is refused all-or-nothing (409 NO_AVAILABLE_KEYS, no keys taken), so refund it at your payment provider. Add a checkout hold only when your checkout is long or the SKU is scarce enough that this happens often. Use reserve and commit only on an allocation the Content Owner put in launch mode (hotDropMode: true).

Three ways keys are set aside#

Checkout holdLaunch reservation (hot drop)Launch-window reservation
Who creates itYou, per cartYou, per cartThe Content Owner, per allocation
HowPOST /orders/holdPOST /orders/reserveSet by the Content Owner; you see launchWindow on GET /allocations
Where it worksAny allocation, when GET /whoami reports capabilities.checkoutHoldEnabled: trueOnly allocations with hotDropMode: trueAllocations the Content Owner gives a launch window
How long30 minutes by default (a platform setting; not chosen per request, not extendable)About 60 secondsFrom launchWindow.startsAt to launchWindow.endsAt
What it guaranteesUnits out of your allocation and stock while the buyer pays, and the price bound when it was created (API model)Units for a launch-scale checkoutKeys held for your store only; your allocation's remaining still caps what you take
How it endsPOST /orders with checkoutHoldId consumes it; DELETE /orders/hold releases it; or it expiresPOST /orders/commit consumes it; or it expiresThe window closes; unused keys return to the shared pool
How to read itGET /orders/hold/{holdId}The POST /orders/reserve answer (expiresAt)launchWindow on GET /allocations and GET /allocations/{id}
GuideCheckout holdsHot dropCatalog and allocations

Two other words sound alike and are not reservations:

  • Your allocation is a quota: how many keys of a SKU the Content Owner lets you take (quantityLimit), and how many are left (remaining). It does not hold any key for you. Ask for more with POST /allocations/requests.
  • order.reserved is an order event: a pre-order or a launch reservation was accepted and its keys come later.

A hold and a launch reservation are not orders: neither outlives its lifetime, and neither moves money.

The stock numbers#

GET /availability answers several numbers for one allocation. They answer different questions:

FieldQuestion it answers
allocationRemainingHow many more keys does my allocation let me take? (quantityLimit minus the keys you have taken and the keys reserved against it)
inventoryAvailableHow many keys does the Content Owner have for me? (their shared pool plus any stock dedicated to your allocation: sharedPoolAvailable + dedicatedAvailable)
availableThe smaller of the two: keys an order could take if nothing were held
heldQuantityKeys inside live checkout holds on this allocation right now (null when the hold ledger could not be read)
sellableNowavailable minus heldQuantity: what POST /orders can take right now. Gate checkout on this one

maxFulfillableQuantity is the same value as sellableNow under its older name, and cannotFullyFulfill and allOrNothingWillFail are the same boolean under two names. Read either; both are kept so existing integrations keep working.

On GET /allocations, remaining is the allocation's own count (the same as allocationRemaining): it says nothing about the Content Owner's stock.

Low stock#

Three events tell you an allocation is running out. They mean different things:

EventSent whenHow often
allocation.running_lowremaining falls to or below the allocation's threshold: your replenishThreshold (PATCH /allocations/{id}) when you set one, otherwise 10% of quantityLimit, rounded downOnce per crossing. Again only after remaining has risen above the threshold and fallen to it again
allocation.low_stockremaining is above zero and at or below a fixed 10% of quantityLimit (stated in threshold)With every allocation update while it stays there
allocation.depletedremaining reaches zeroWith every allocation update at zero

Page a person or reorder on allocation.running_low. Use allocation.low_stock only if you want a signal on every update while stock is low. All three are about your allocation's quota, not the Content Owner's stock: when the Content Owner runs out first, GET /availability shows inventoryAvailable at zero.

A threshold also drives automatic top-ups. The PATCH /allocations/{id} answer says what a crossing will do under the Content Owner's rules (effective): top the allocation up, file an allocation request for the Content Owner, or nothing.

In the sandbox#

  • SANDBOX-ALWAYS-001 and SANDBOX-EUR1-001 are in launch mode, so POST /orders/reserve and POST /orders/commit can be rehearsed on them. The other magic SKUs are not.
  • Checkout holds work in the sandbox when GET /whoami reports capabilities.checkoutHoldEnabled: true.
  • POST /webhooks/{id}/test with a sandbox key sends a sample of any event, including allocation.running_low, allocation.low_stock and allocation.request_cancelled, so your receiver can be tested without draining an allocation.

What links here

Published guides that link to this page.

Search docs

Search documentation…