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 the quantity-rules implementation decisions
Damian Legawiecd07f6c1d1a34
diff --git a/docs/plans/6.0-b2b-quantity-rules.md b/docs/plans/6.0-b2b-quantity-rules.mdindex 6a089af76b..aa19ff2402 100644--- a/docs/plans/6.0-b2b-quantity-rules.md+++ b/docs/plans/6.0-b2b-quantity-rules.md@@ -1,10 +1,10 @@# B2B Quantity Rules (MOQ, Order Multiples, Purchase Unit)-**Status:** Draft — design finalized 2026-08-30 (one-question-per-entity doctrine, decisions.md 2026-08-30), nothing built+**Status:** In progress — design finalized 2026-08-30 (one-question-per-entity doctrine, decisions.md 2026-08-30); implementation started 2026-08-31 (backend + dashboard; storefront deferred)**Target:** Spree 6.0**Depends on:** B2B Wholesale Shipping (6.0-b2b-wholesale-shipping.md — packing chain on variants), B2B Companies & Catalogs (6.0-b2b-companies-and-catalogs.md), Extendable Validations (6.0-extendable-validations.md), Service Workflows (6.0-service-workflows.md)**Author:** Damian + Claude-**Last updated:** 2026-08-30+**Last updated:** 2026-08-31## Summary@@ -101,6 +101,27 @@ Multiple → Carton → Pallet.they are from it ("$180 to reach the $500 minimum"), so the check is a`Carts::Complete` validation plus a computed shortfall the cart serializerexposes.+- **`units_per_carton` lands with this plan, not with wholesale shipping**+ (2026-08-31, implementation review): `purchase_unit: 'carton'` is+ meaningless without the divisor, and the wholesale-shipping plan is design+ only. This plan adds `units_per_carton` to `spree_variants`; the wholesale+ plan still owns the rest of the packing chain (`carton_package_type_id`,+ `carton_weight`, `cartons_per_pallet`) and must not re-add this column.+- **Completion refuses an out-of-rule line, it does not warn** (2026-08-31):+ rules can change between add-to-cart and checkout, so `Carts::Complete`+ re-checks every line through `Checkout::Requirements` with+ `completion: true` — the same place out-of-stock and discontinued lines+ are refused — naming the nearest valid quantities. Staff-initiated carts+ skip both this and the order minimum, matching the `po_number` precedent+ (`created_by_id` present).+- **The order minimum is advisory before completion, blocking at it**+ (2026-08-31): the shortfall rides `Checkout::Requirements` as an advisory+ requirement so the buyer sees "$180 to reach the $500 minimum" while they+ can still act on it, and becomes refusal only when completion is attempted.+- **The storefront ships separately** (2026-08-31): the Next.js selector,+ carton display and shortfall banner are a follow-up on the storefront+ repo. The Store API exposes everything they need (resolved rules on the+ variant, minimum + shortfall on the cart), so the two land independently.## Design Details@@ -234,7 +255,13 @@ behavior (MOQ 1, multiple 1, unit display).(existing extendable-validations constraint) — that is what makes theenforcement complete.- Carton/pallet packing data is owned by `6.0-b2b-wholesale-shipping.md`;- this plan reads it, never redefines it.+ this plan reads it, never redefines it — **except `units_per_carton`,+ which this plan adds** (2026-08-31). The wholesale plan must not re-add+ that column.+- **A new variant attribute must be permitted in three places** or a write+ path silently drops it: the inline `variants: [...]` list on+ `Admin::ProductsController`, the nested `Admin::Products::VariantsController`,+ and `Seller::ProductsController` (duties-plan constraint).- **Commercial terms are catalog data.** No purchase-term settings on`Spree::Channel` (a surface's terms are its default catalog's) and no newterm columns on variants beyond the base rules — a new kind of term@@ -245,7 +272,10 @@ behavior (MOQ 1, multiple 1, unit display).## Open Questions-1. **Carton-denominated minimums** ("minimum 10 cartons per order") —+1. **Storefront quantity UX** (deferred 2026-08-31, not blocked) — the+ selector, carton display and shortfall banner are a follow-up on the+ `spree/storefront` repo. The Store API already exposes what they need.+2. **Carton-denominated minimums** ("minimum 10 cartons per order") —deferred; the amount minimum covers the common case, and a carton-countminimum needs the freight summary at completion time anyway. (Thecatalog/price-list ownership question this plan previously carried wasdiff --git a/docs/plans/6.0-b2b-wholesale-shipping.md b/docs/plans/6.0-b2b-wholesale-shipping.mdindex c9e23feb10..d26de1cf24 100644--- a/docs/plans/6.0-b2b-wholesale-shipping.md+++ b/docs/plans/6.0-b2b-wholesale-shipping.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** Delivery Profiles (6.0-delivery-profiles.md), Delivery Method Rules (6.0-delivery-method-rules.md), Delivery Rate Provider (6.0-delivery-rate-provider.md), B2B Companies & Catalogs (6.0-b2b-companies-and-catalogs.md), Duties & Custom Fees (6.0-duties-and-custom-fees.md), Service Workflows (6.0-service-workflows.md)**Author:** Damian + Claude-**Last updated:** 2026-08-30+**Last updated:** 2026-08-31## Summary@@ -385,6 +385,11 @@ empty, and nothing changes for stores that never fill them.and the default `PackageType` row (after phase 3).- **Don't build "freight quoted later" as a zero-cost priced rate.** The`unpriced` flag is the mechanism; a $0 rate renders as free shipping.+- **`units_per_carton` is already on `spree_variants`** — added by+ `6.0-b2b-quantity-rules.md` (2026-08-31), which needs the divisor for its+ carton purchase unit. This plan adds the rest of the chain+ (`carton_package_type_id`, `carton_weight`, `cartons_per_pallet`) around+ it and must not re-declare it.- **Don't add carton dimension columns to `spree_variants`.** Cartongeometry lives on the referenced `PackageType`; only packing facts(`units_per_carton`, `carton_weight`) sit on the variant.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex d3010f4902..78e4cfb651 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -4585,3 +4585,41 @@ one-question-per-entity doctrine exists to prevent.Plans amended: `6.0-price-list-automatic-pricing.md` (Key Decisions,Resolution), `6.0-catalog-agreement-rework.md` (Constraints — owned listsare no longer rule-free).++## 2026-08-31 — Quantity rules: the divisor ships early, completion refuses, the storefront follows++Implementation of `6.0-b2b-quantity-rules.md` settled four questions the+design left to the build.++**`units_per_carton` moves to the quantity plan.** The carton purchase unit+is a display vocabulary that needs a divisor, and the wholesale-shipping+plan that owns the packing chain is design only. Rather than ship a flag+that does nothing, the single column lands with the feature that first uses+it; wholesale shipping still owns `carton_package_type_id`,+`carton_weight` and `cartons_per_pallet` and must not re-declare it. The+alternative — waiting — would have meant either no carton vocabulary in 6.0+or pulling an unbuilt plan forward wholesale.++**Completion refuses an out-of-rule line rather than warning.** Rules can+change between add-to-cart and checkout (a company reassigned to a different+tier, a catalog term edited), so every line is re-checked at completion+through `Checkout::Requirements` with `completion: true` — the same place+out-of-stock and discontinued lines are already refused — with the message+naming the nearest valid quantities. Letting a below-MOQ wholesale order+through is the five-figure surprise the feature exists to prevent.++**The order minimum is advisory before completion and blocking at it.** The+shortfall rides the requirements feed as an advisory requirement so the+buyer reads "$180 to reach the $500 minimum" while they can still act, and+becomes refusal only when completion is attempted. Staff-initiated carts+(`created_by_id` present) skip both the line re-check and the minimum —+the same exemption `po_number_required` takes, for the same reason: staff+key in what the buyer actually negotiated.++**The storefront ships separately.** The Next.js selector, carton display+and shortfall banner land on `spree/storefront` afterwards. The Store API+exposes the buyer's *resolved* rules on the variant and the minimum plus+shortfall on the cart, so neither side blocks the other.++Plans amended: `6.0-b2b-quantity-rules.md` (implementation started),+`6.0-b2b-wholesale-shipping.md` (`units_per_carton` no longer its column).