Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
index 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 serializer
exposes.
+- **`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 the
enforcement 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 new
term 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-count
minimum needs the freight summary at completion time anyway. (The
catalog/price-list ownership question this plan previously carried was
diff --git a/docs/plans/6.0-b2b-wholesale-shipping.md b/docs/plans/6.0-b2b-wholesale-shipping.md
index 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`.** Carton
geometry 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.md
index 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 lists
are 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).