Katana: on-hand, committed and expected stock
Why Katana’s inventory contract needs several quantities, with a worked planning example and explicit limits on what those numbers prove.
- Variant + location
- On hand / committed / expected
- Explicit availability model
Investigation question
Why can a single “stock” number mislead an inventory integration? Katana exposes quantities for physical holdings, commitments and expected supply. This investigation follows the different questions those fields answer at a specific variant and location.
Observed
The inventory reference identifies an inventory point by variant_id and location_id. It distinguishes quantity_in_stock, quantity_committed and quantity_expected, rather than collapsing physical holdings and future obligations into one field. The same object includes a safety-stock threshold and separate valuation fields. Sales-order rows and manufacturing relationships add context to demand, while purchasing and production can contribute future supply. A stock reading therefore needs both its identity and its quantity type. A number without a location, variant and meaning is an incomplete observation.
Inferred
On-hand stock answers a physical-balance question. Commitments describe demand already associated with that stock; expected supply describes a future event. Adding expected units to on-hand units may help planning, but it does not prove those units can be picked today. Likewise, subtracting commitments is a model of availability, not proof of the order in which reservations will win. This distinction is especially useful when a storefront, warehouse and purchasing screen display different numbers. They may be answering different questions correctly. The first diagnostic step is to compare definitions and scope before treating a mismatch as stale synchronization.
Unknown & limitations
No warehouse, order or stock movement was changed for this article. Reservation priority, concurrent allocations, partial receipts, costing adjustments and negative-stock behavior were not reproduced. The public object reference supports the quantity distinction but does not establish serializable allocation or a delivery promise. The diagram is a conceptual view of the contract, not Katana’s internal service architecture.
Domain & data models
Illustrative snapshot: on hand 20 units, committed 8, expected 10. A simple present-stock-minus-demand view gives 12 units; a future planning view gives 22 before any safety-stock allowance. These are worked calculations for understanding the fields, not claims that every Katana availability screen uses those exact formulas. The 10 expected units are not physically present.
Workflows & state machines
A bounded verification can read one variant/location, inspect an order that contributes demand, and inspect the document behind expected replenishment. After a controlled receipt or fulfillment, compare the same fields again. Keep timestamps and document states so a changed balance can be explained. For integrations, name each exported quantity explicitly: “on hand” and “expected” are safer than an ambiguous “stock” field. If only one number can be sent downstream, document the chosen interpretation and what it excludes. This prevents an accidental promise of future inventory as immediately shippable inventory.