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:
- POST /orders/preview: gate the Pay button on
canFulfill. - Charge the buyer.
- 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 hold | Launch reservation (hot drop) | Launch-window reservation | |
|---|---|---|---|
| Who creates it | You, per cart | You, per cart | The Content Owner, per allocation |
| How | POST /orders/hold | POST /orders/reserve | Set by the Content Owner; you see launchWindow on GET /allocations |
| Where it works | Any allocation, when GET /whoami reports capabilities.checkoutHoldEnabled: true | Only allocations with hotDropMode: true | Allocations the Content Owner gives a launch window |
| How long | 30 minutes by default (a platform setting; not chosen per request, not extendable) | About 60 seconds | From launchWindow.startsAt to launchWindow.endsAt |
| What it guarantees | Units 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 checkout | Keys held for your store only; your allocation's remaining still caps what you take |
| How it ends | POST /orders with checkoutHoldId consumes it; DELETE /orders/hold releases it; or it expires | POST /orders/commit consumes it; or it expires | The window closes; unused keys return to the shared pool |
| How to read it | GET /orders/hold/{holdId} | The POST /orders/reserve answer (expiresAt) | launchWindow on GET /allocations and GET /allocations/{id} |
| Guide | Checkout holds | Hot drop | Catalog 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 withPOST /allocations/requests. order.reservedis 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:
| Field | Question it answers |
|---|---|
allocationRemaining | How many more keys does my allocation let me take? (quantityLimit minus the keys you have taken and the keys reserved against it) |
inventoryAvailable | How many keys does the Content Owner have for me? (their shared pool plus any stock dedicated to your allocation: sharedPoolAvailable + dedicatedAvailable) |
available | The smaller of the two: keys an order could take if nothing were held |
heldQuantity | Keys inside live checkout holds on this allocation right now (null when the hold ledger could not be read) |
sellableNow | available 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:
| Event | Sent when | How often |
|---|---|---|
allocation.running_low | remaining falls to or below the allocation's threshold: your replenishThreshold (PATCH /allocations/{id}) when you set one, otherwise 10% of quantityLimit, rounded down | Once per crossing. Again only after remaining has risen above the threshold and fallen to it again |
allocation.low_stock | remaining is above zero and at or below a fixed 10% of quantityLimit (stated in threshold) | With every allocation update while it stays there |
allocation.depleted | remaining reaches zero | With 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-001andSANDBOX-EUR1-001are in launch mode, soPOST /orders/reserveandPOST /orders/commitcan be rehearsed on them. The other magic SKUs are not.- Checkout holds work in the sandbox when
GET /whoamireportscapabilities.checkoutHoldEnabled: true. POST /webhooks/{id}/testwith a sandbox key sends a sample of any event, includingallocation.running_low,allocation.low_stockandallocation.request_cancelled, so your receiver can be tested without draining an allocation.