Skip to main content
Version: Next

Stock: reservation, preorder and low stock alerts

Added in Thelia 3.4.

Three features sit on top of the stock of a combination:

  • Preorder: keep selling a combination after its stock reaches zero.
  • Reservation: hold the stock of a cart while the customer checks out.
  • Low stock alert: get an e-mail when a combination runs low.

product_sale_elements.quantity stays the physical stock. What a customer can buy is computed beside it, and the cart, the order, the quick order, the loops, the availability facet and the front API all read that same number. A product page, a product card, the cart and the API show the same quantity.

The sellable quantity is the physical stock, plus what the combination may sell below zero, less what other carts hold.

Preorder​

Each combination has an At zero stock setting, in the product's Combinations tab:

ValueBack-office labelEffect
0Refuse the saleThe sale is refused at zero. This is the default and the behaviour of earlier versions.
1Keep sellingThe sale goes on without limit. The stock can go below zero.
2Sell up to a limit (preorder)The sale goes on until the stock is Preorder limit units below zero. With a limit of 10 and a stock of 0, the 11th unit is refused.

Restock date is the date the merchant expects new stock. It is shown to customers and kept on the orders.

An order line sold above the physical stock is flagged as a preorder, and keeps the restock date of that moment. The order confirmation and notification e-mails of the default e-mail theme print it. In the back office, the order list can be filtered on preorder lines (with or without) and flags an order that holds one.

Preorder follow-up​

Catalog > Preorder follow-up (/admin/preorders, view right on products) lists the combinations whose stock is below zero and that are sold below zero. For each one it shows:

  • To order: the stock the combination lacks. With a stock of 3 and open orders of 2, 4 and 2, the merchant has to order 5.
  • Open orders that are concerned;
  • the Restock date.

The list is sorted by restock date, then by shortage, 25 rows per page. The own stock of sale units is not counted.

Stock reservation​

Reservation is off by default. A shop that does not turn it on runs as before.

Turn it on in Configuration > Store info, with these settings:

SettingVariableDefaultMeaning
Reserve the stock of a cartstock_reservation_enabled0Turns the feature on.
The reservation startsstock_reservation_scopecheckoutcheckout: when the customer enters the checkout. cart: as soon as an item is added, and after each change of the cart.
Reservation duration (minutes)stock_reservation_duration15How long the lines of a cart are held after the last step.

While a line is held, until cart_item.reserved_until, no other cart can buy that unit. A reservation past its time is never counted, whether or not the purge ran.

When two customers pay for the last held unit at the same moment, one order is created and the other is refused with an explicit message (409 on the front API).

A line stays held for at most four reservation durations from its first hold. Past that, holding it again does not push its date back.

In the Combinations tab, the sellable quantity is shown under the physical stock ("Sellable: unlimited" when the combination sells without limit). Hover it to see the quantity held by carts, the number of carts and the nearest expiry. A bundle shows nothing there.

Limits on holds​

New holds are capped: 60 per hour for a cart and 300 per hour for a client address (no address cap on the command line). Extending or changing a line already held is free.

Set the caps with the environment variables THELIA_STOCK_RESERVATION_RATE_LIMIT_PER_CART and THELIA_STOCK_RESERVATION_RATE_LIMIT_PER_CLIENT.

Over the cap, the checkout API and the express checkout answer 429 with a Retry-After header. A cart change keeps the lines it could not hold unreserved. Flexy shows the delay at the checkout step. A line that is out of stock is refused as before, not as a rate limit.

Purge​

stock:reservation:purge clears the reservations that ran out. See stock:reservation:purge. The schedule runs it every 10 minutes. Change the schedule with THELIA_SCHEDULE_STOCK_RESERVATION_PURGE, a cron expression.

For a theme​

A theme that has its own checkout calls CheckoutFacade::holdStock() when the customer enters it.

Low stock alert​

The shop-wide Low stock threshold is a setting in Configuration > Store info (low_stock_threshold, 5 by default). A combination can override it with its own Low stock threshold in the Combinations tab. Empty means the shop's threshold applies.

When a stock change crosses the threshold, the shop e-mails the low_stock_alert message to its notification addresses. The Dashboard lists the combinations under their threshold. The threshold does not apply to a bundle, whose stock is the one of its components: a bundle can either be ordered or not.

The message is rendered from the active e-mail template. A shop that uses an e-mail template of its own must add low_stock_alert.html.twig and low_stock_alert.txt.twig to it. Until then the alert is logged and not sent. The order is never affected.

If the StockAlert module also mails the shop owner under its own threshold, the shop gets both mails. Keep one of the two.

Developer reference​

API​

On the front API, a combination exposes:

FieldMeaning
availableQuantityThe sellable quantity. Left out when it is unlimited.
isPreorderWhether the next unit sold is a preorder.
outOfStockPolicy0, 1 or 2.
restockDateThe restock date.

preorderLimit is also on the product read. These fields are in the listings too.

On the admin API, /api/admin/product_sale_elements reads and writes outOfStockPolicy, preorderLimit, restockDate and lowStockThreshold.

Loops​

LoopNew outputs
product_sale_elementsOUT_OF_STOCK_POLICY, PREORDER_LIMIT, RESTOCK_DATE
order_productIS_PREORDER, RESTOCK_DATE

Classes​

ClassRole
Thelia\Domain\Catalog\Stock\SellableStockThe sellable quantity of a combination.
Thelia\Domain\Catalog\Stock\PreorderRuleThe one rule that tells a preorder apart.
Thelia\Domain\Catalog\Stock\OutOfStockPolicyThe three policies.
Thelia\Domain\Catalog\Stock\StockSettingsThe shop-wide settings.

Events​

ConstantEvent classWhen
TheliaEvents::PRODUCT_SALE_ELEMENTS_STOCK_CHANGED (thelia.pse.stock_changed)StockLevelChangedEventAfter a stock change is committed.
TheliaEvents::PRODUCT_SALE_ELEMENTS_LOW_STOCK_REACHED (thelia.pse.low_stock_reached)LowStockReachedEventThe stock crossed the threshold. The shop mails the alert on this event. A module can plug a restocking.
TheliaEvents::STOCK_RESERVED (thelia.pse.stock_reserved)StockReservedEventLines of a cart are reserved.
TheliaEvents::STOCK_RELEASED (thelia.pse.stock_released)StockReleasedEventLines of a cart are released.

The stock change event is sent once the transaction is committed. Inside a transaction of the caller it waits for the end of the request, the command or the message, and it is never sent when that transaction is rolled back. It is dispatched by an order, a change of order status, the back-office edit of a combination, PSEFacade, the stock import, the reception of an order return, and a PUT or PATCH of /api/admin/product_sale_elements or of /api/admin/products/{id}.

The reservation events are sent once per cart, never on a rollback, with the cart id and the lines (cart item id, combination id, quantity). A line is told reserved once and released once. Extending a hold tells nothing. Changing the quantity of a held line tells the old quantity released, then the new one reserved. A line is released when it is deleted, when its cart is emptied or purged, when it is ordered, and when stock:reservation:purge clears its date. A listener that fails is logged and stops nothing.