Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Record holding the shelf at zero as a decision, not a detail
Łukasz Adamczyka6dc774bc5a8
diff --git a/docs/plans/6.0-typed-stock-movements.md b/docs/plans/6.0-typed-stock-movements.mdindex 46a985b886..ea6f76d425 100644--- a/docs/plans/6.0-typed-stock-movements.md+++ b/docs/plans/6.0-typed-stock-movements.md@@ -150,7 +150,9 @@ The `min_quantity` validation goes away. It exists to stop a movement from driviA negative `count_on_hand` therefore stops meaning "oversold" — that is `allocated_count > count_on_hand` now — and comes to mean something narrower: goods left that Spree never saw arrive. A receiving gap, visible as a number, and self-healing the moment the missing `received` movement lands. Availability is unaffected on the way through: on-hand 0 / allocated 1 / available −1 becomes on-hand −1 / allocated 0 / available −1, because the promise had already been subtracted and only the shelf changed.-This is why the non-negative guard keys off the write rather than off `backorderable?` / `preorder?` as `verify_count_on_hand?` does today. Specifically it keys off `force` (revised 2026-08-17): the `shipped` kind alone would hand the same licence to a stock transfer, which moves goods nobody promised and cannot send what the warehouse does not have — and did, until the transfer's own precondition was tightened to compare against the quantity being moved rather than merely against zero. `received` cannot go negative by construction, and `adjusted` keeps the guard — a hand-typed count landing below zero is a typo, not a fact.+**The non-negative guard keys off the write, not off the variant** (decided 2026-08-17, and an addition to what this plan originally asked for). `verify_count_on_hand?` exempts a backorderable or pre-order level from the check today, because a negative shelf was how an oversell was written down and those are the levels allowed to oversell. This plan deletes that representation, so the exemption loses its only purpose and both clauses come out. What replaces them is `force` (revised from the `shipped` kind on the same date): the kind alone would hand the same freedom to a stock transfer, which moves goods nobody promised and cannot send what the warehouse does not have — and did, until the transfer's own precondition was tightened to compare against the quantity being moved rather than merely against zero. `received` cannot go negative by construction, and `adjusted` keeps the guard — a hand-typed count landing below zero is a typo, not a fact.++Dropping the exemptions is a behaviour change in its own right, so it is recorded rather than folded in silently: `Variant#set_stock(-5)` and `PATCH /stock_levels` with a negative count against a backorderable level used to persist, and now raise. No gem code writes a negative count any more except a forced dispatch, so what this reaches is host-app scripts and hand edits, and what they lose is the ability to record a number no warehouse can hold. The specs asserting the old permission — the backorderable and pre-order arms of `stock_item_spec.rb`'s `count_on_hand` matrix — were inverted on purpose.`force` reaches the write as a transient attribute on the movement, threaded `Fulfill(force:)` → `StockLocation#unstock(force:)` → `move(force:)`, never persisted — the shape `Fulfillment#notify_customer` already uses for an instruction about one dispatch. And because a merchant needs to be told rather than 500'd, `Fulfillments::Fulfill` refuses a dispatch the shelf cannot cover before writing anything, with a message saying to correct the count or force it. Note the ordering that makes this work: a canceled fulfillment re-allocates on its way out, so the check reads its manifest rather than the nothing it currently holds.@@ -480,6 +482,7 @@ Two things that are **not** bridges and therefore have nothing to remove here: t- **Don't create `StockMovement` records directly.** Go through `StockLocation#restock` / `unstock` (and `allocate` / `release` / `adjust` once they exist) so rows come out typed when this plan lands.- **Don't write `count_on_hand` outside a movement.** No new callers of `adjust_count_on_hand`, `set_count_on_hand`, `set_stock` or `update_all(count_on_hand:)`, and no new callers of `restock_backordered` — it is being deleted.+- **Don't write a negative `count_on_hand`.** A level is held at or above zero whatever the variant's backorder or pre-order settings say, and only a forced dispatch is exempt. Code that expressed an oversell as a negative shelf expresses it as `allocated_count` above `count_on_hand` instead.- **Don't build business logic on `originator_type`.** It is gone in 6.1. Anything that needs to know why stock moved is waiting on `kind`.- **Read availability through `Stock::Quantifier`, `StockLevel#available_count` or `#allocated_count`** — never raw `count_on_hand`. The shims already return correct answers today (`allocated_count` is 0), so code written against them keeps working unchanged when the column arrives. New raw `count_on_hand` reads are the main way this plan can regress.- **Don't assume stock leaves at placement.** Anything that reconciles on-hand against a warehouse, or reports "units removed", should key off fulfillment rather than order placement.diff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rbindex a488e9b443..436a324016 100644--- a/spree/core/app/models/spree/variant.rb+++ b/spree/core/app/models/spree/variant.rb@@ -629,17 +629,13 @@ module SpreeSpree::Pricing::Resolver.new(context).resolveend- # Sets the stock for the variant at a given location.- # Mirrors set_price: find-or-initialize, set attrs, save only if persisted.- # @param count_on_hand [Integer] the count on hand- # @param backorderable [Boolean] the backorderable flag- # @param stock_location [Spree::StockLocation] the stock location (defaults to store default)- # @return [void]# Sets the count at a location. The correction goes through an `adjusted`# movement so it shows up in the stock history like every other change.+ # A count below zero is refused whatever the variant's backorder settings+ # say, so a caller passing one gets ActiveRecord::RecordInvalid.## @param count_on_hand [Integer] the count the level should end up at- # @param backorderable [Boolean, nil]+ # @param backorderable [Boolean, nil] left as it is when nil# @param stock_location [Spree::StockLocation, nil] defaults to the store's# @return [void]def set_stock(count_on_hand, backorderable = nil, stock_location = nil)