Stock
Track stock per product at each store location and food truck — holds at checkout, sales, returns, backorders, low stock alerts and what customers see.
Stock
Storefront can count stock for the products you choose, separately at each store location and food truck, and stop selling a product where it has run out. Stock tracking is opt-in per product: products that don't track stock are never limited.
Stock tracking ships with Storefront v0.4.25 and needs its database migration (2026_10_13_000000_create_inventory_tables); until the migration has run, nothing is limited. It is deliberately simple — one count per product per location. A later version will offer an opt-in move to the Pallet warehouse and inventory module.
Turning on stock tracking
Open the product in Storefront → Products. A new product has to be saved once before its stock can be set.
In the Stock section, turn on Track stock for this product.
For each store location and food truck, enter the count On hand, an optional Low at threshold, and whether to allow Backorders.
Optionally add a note for the change (e.g. delivery received) and click Save stock.
Each row shows:
| Column | Meaning |
|---|---|
| On hand | The count at that location. Editing it records a restock (up) or an adjustment (down). |
| Held | Units held by checkouts that are still being paid |
| Available | On hand minus held — what can be sold now |
| Low at | The low stock threshold. The location is low when what's available is above zero and at or below this number. |
| Backorders | When on, the product keeps selling at that location after it runs out |
Turning tracking off stops limiting the product but keeps its counts.
How stock moves
| Moment | What happens |
|---|---|
| Checkout starts | The units in the cart are held for 15 minutes while the customer pays. It's all or nothing: if any line is short, nothing is held and checkout is refused. |
| Order placed | The held units are sold and taken off the count on hand. A hold that expired while the customer was paying is sold all the same, since the customer has paid. |
| Checkout abandoned | Holds that expire are released. The storefront:release-inventory command runs every minute to release them. |
| Order canceled | The units sold are returned to the location they came from, once per order, however the order was canceled. |
| Order edited | Units added or removed by an edit are taken or returned directly. An edit doesn't hold stock or check availability first. |
The Recent changes list under the table shows each movement — Restocked, Adjusted, Held for a checkout, Released from a checkout, Sold, Returned (order canceled), Order edited — with its quantity, note and time.
Which location an order sells from
A cart line sells from the store location or food truck it was added for: the store_location sent when adding to the cart, which defaults to the store's first location. A tracked product with no stock entered at that location can't be sold from there.
Finding products to restock
In Storefront → Products, two smart groups in the category sidebar list:
- Unavailable — products switched off, and products that track stock with nothing available at any location (and no backorders).
- Low stock — products with a location at or below its low stock threshold.
Product cards show Unavailable for these products and Only N left when stock is low.
What customers see
The product resource returned to apps carries the stock:
{
"id": "product_4Hx9zL2",
"name": "Sourdough loaf",
"is_available": true,
"track_inventory": true,
"in_stock": true,
"inventory": {
"tracked": true,
"in_stock": true,
"available_total": 3,
"low": true,
"locations": [
{ "id": "inventory_7Lq2mX4", "location": "store_location_2Bc8dE1", "location_type": "store_location", "quantity": 4, "reserved": 1, "available": 3, "low_stock_threshold": 5, "allow_backorder": false, "low": true }
]
}
}in_stockisfalsewhen the product is switched off or tracks stock with nothing sellable anywhere. Products that have run out are still listed (unlike products switched off with Is Available), so apps can show them as out of stock.inventory.trackedisfalse(andin_stocktrue) for products that don't track stock.
When stock ran out between adding to the cart and paying, checkout initialization fails with 422:
{
"errors": ["Some items in your cart are no longer available."],
"code": "cart_items_unavailable",
"items": [{ "id": "cart_item_8Hd3kP1", "product_id": "product_4Hx9zL2", "name": "Sourdough loaf", "available": 1 }]
}items lists the short lines with what is still available. Let the customer change the cart and try again.
The Storefront App shows Out of stock and disables Add to cart when in_stock is false, shows Only N left when stock is low, caps the quantity at what's available, and lists the unavailable items when checkout is refused.
Internal API
The console reads and writes stock through GET and PUT /storefront/int/v1/products/{id}/inventory. The PUT body is:
{
"track_inventory": true,
"locations": [
{ "location": "store_location_2Bc8dE1", "quantity": 24, "low_stock_threshold": 5, "allow_backorder": false }
],
"note": "Delivery received"
}