Inventory

Stock per warehouse and shelf, every unit in and out as a line of a ledger, orders reserved until they ship, counts and adjustments with a reason, reorder points.

kitloom/inventory · admins: kitloom/inventory-filament, kitloom/inventory-nova

A warehouse under the shop. Stock sits in locations — a warehouse, a shelf in it, a second store — and every unit that comes in or goes out is a line of a ledger: a receipt from a supplier, a delivery to a customer, a box moved to another shelf, what a count found. What is on hand is the sum of those lines, never a number someone typed, and an order holds its units from the moment it is placed until it ships.

What it does for the shop

Install it and the shop's stock moves here:

• A product that manages its stock becomes an item the first time the warehouse hears of it — a sale, a receipt, a save of the product, or inventory:import-products for the whole catalogue at once — with the product's SKU, name and barcode, and the quantity the product had as the opening count in the default warehouse. Nothing is lost on the way.
• An order placed reserves its units: they stay on the shelf but are nobody else's. Paying changes nothing. The order completed (or shipped, with kitloom/shipments) moves them to the customers' location; cancelled or failed, it lets them go — and an order cancelled after it shipped takes them back on a receipt. A pending order that is never paid holds its units as long as the shop's Hold stock says, then the warehouse lets them go.
• The product's stock is what is available online: on hand less reserved, over the warehouses that sell online — written into the product after every move, so the catalogue, the feeds, the structured data and an export read it as before. On the product form the number is read-only: it is changed here, with a reason and a person behind it.
• Backorders stay the product's choice. A product that allows them is sold past its stock; the reservation goes below zero on the default warehouse, and the next receipt fills it.

The shop's own low-stock emails and notices go on working: the warehouse tells the shop every change an order makes.

Screens

Inventory → Items. Everything the warehouse counts: a product of the shop, or a thing of the warehouse's own — packaging, a component, what is sold only at the counter. Each item has a SKU, a barcode, a unit (pieces, kg, litres: quantities take three decimals), its average cost, and a reorder point with a quantity to buy. An item's page shows its level at every location and its own lines of the ledger. Adjust sets what a location has, with a reason: count, damaged, lost, found, correction.

Inventory → Locations. The warehouses and the shelves in them. A warehouse that sells online fills the shop's orders; one that does not (an outlet, a van) keeps its stock to itself. A location may allow negative stock for a shop floor that sells faster than it scans; the rest refuse a move past what they hold. The virtual locations the ledger needs — Suppliers, Customers, Inventory adjustments — are made on first use and stay out of the way.

Inventory → Transfers. The documents the moves hang on:

• Receipt — goods in from a supplier to a warehouse, each line at its price, which moves the item's average cost.
• Delivery — goods out to a customer; the shop's orders make these.
• Internal — from one of the site's locations to another.
• Adjustment — what a count found or lost, against the adjustments location.

A transfer is drafted with its lines (type a barcode or a SKU to add one), made ready, then done — with the quantity that actually came where a line fell short, and the rest kept open on a new draft when it is still expected. A transfer done is never edited: a mistake is a move the other way.

Inventory → Moves. The ledger itself, newest first: when, what, how many, from where to where, on which transfer, by whom, and why.

Inventory → Counts. Pick a location, count the shelf, type what you found: the differences become one adjustment with a line per item.

Inventory → Reports. On hand by location, the stock's value at average cost, and the items at or under their reorder point counting what is on its way.

Inventory → Settings. The default warehouse (goods come in there, orders are filled from it first), whether the products' stock is written from here, and how often a location is due for a count.

Permissions

manage_inventory does everything above; view_inventory looks at the items, the levels, the ledger and the reports. The roles that manage the shop's settings hold the first, the shop's order managers the second.

For AI agents

With kitloom/ai, an agent with view_inventory reads the levels, the ledger and the transfers (inventory_levels, inventory_moves, inventory_transfers); one with manage_inventory adjusts, receives and transfers (inventory_adjust, inventory_receive, inventory_transfer, inventory_items_save). The product's stock is a projection: an agent that wants it changed uses inventory_adjust, not the product.

Console

• inventory:import-products — an item for every product that manages its stock, its quantity as the opening count. Run once after installing on a shop that sold already; safe to run again.
• inventory:rebuild [--check] — the levels from the moves; --check only compares (kitloom/health runs the same check).
• inventory:release-expired — the holds of unpaid orders past their time, every five minutes from the scheduler.

Also

With kitloom/spreadsheets the items, the levels and the moves go out as CSV or Excel, the items come in (never their quantities), and a count sheet — SKU, location, counted — comes in as adjustments. With kitloom/notifications the owner is told when an item reaches its reorder point. With kitloom/webhooks other systems hear inventory.level.changed and inventory.transfer.done. Erase Personal Data blanks the customer on their deliveries.