Distribu

Stock tracking

Every product has a stock field — a whole number representing how many units you have on hand. Distribu updates it automatically as orders are placed and surfaces warnings when stock gets low.

How stock decrements

When an order is placed — whether on the storefront, from Orders → New order in the dashboard, or via the REST API — stock drops atomically with the order write:

  1. The server validates every line item against current stock. If any line's quantity is more than we have, the order is rejected with Not enough stock for X. Only Y available.
  2. It creates the order and its line items.
  3. It decrements stock for each line item.

Either the whole order succeeds and every product's stock drops, or nothing happens. There's no intermediate state where stock is decremented but the order isn't saved.

Stock does not restore automatically when an order is cancelled or refunded. If you want to put the units back, edit the product manually and bump the stock back up. This is intentional — most cancellations in B2B are for orders that already shipped, so the units are gone.

Low-stock threshold

Any product with stock > 0 and stock ≤ 5 is considered low stock. Two things happen when a product drops to or below that level:

1. Storefront warning

The storefront cart shows a yellow "Only N left" next to the quantity input. This also shows in the dashboard's /dashboard/orders/new product picker so your staff can see it before confirming an order.

2. Low-stock email

After every storefront order is placed, if any of the ordered products dropped to or below 5, an email goes to every OWNER and ADMIN on your team with the product name, SKU, and current stock level.

The email is sent once per order, not once per product — so an order that dropped three different SKUs into low stock sends one email listing all three.

The threshold of 5 is hardcoded right now. If you want a per-product or configurable value, email us — it's a commonly requested feature.

Inventory health panel

The dashboard home screen's Inventory health panel (at /dashboard) gives you a running count:

  • Healthy — active products with stock > 5
  • Low stock — active products with stock between 1 and 5
  • Out of stock — active products with stock = 0

Inactive products don't count — only your live catalog.

Out of stock behavior

A product with stock = 0 is still visible on the storefront (so customers know it exists), but can't be added to the cart. On the storefront product page it's flagged as "Out of stock". On the dashboard it appears with a red stock cell.

To hide a sold-out product entirely, deactivate it — see Adding products → Activate / deactivate.

Adjusting stock manually

Four ways to change stock outside of order placement:

1. Edit one product

Open the product's edit page and change the Stock qty field. Save. Done — the change is written directly with an audit log entry.

2. Bulk adjust

Select multiple products in the Inventory list and use the Stock bulk action. Two modes:

  • Set — set every selected product to the same stock count (e.g. "set to 100").
  • Delta — add or subtract the same amount from every selected product (e.g. "−10" to deduct 10 units from all selected products).

Negative stock is clamped to 0.

3. CSV import

Upload a CSV with updated stock values. Rows with an existing SKU are updated; new SKUs are created. See CSV import for the full flow.

4. REST API

PATCH /api/v1/products/{id} with a new stock value. See Products endpoints.

All four paths write the same audit-log entry (ProductUpdated or ProductBulkUpdated) so you can see who changed what in Settings → Audit log.

Next: CSV import.