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
Changed the wholesale shipping plan to record what shipped and what it excludes
Damian Legawiecceb3ef2be4d6
diff --git a/docs/plans/6.0-6.1-b2b-payment-terms.md b/docs/plans/6.0-6.1-b2b-payment-terms.mdindex b17341f9c4..88e32ae86a 100644--- a/docs/plans/6.0-6.1-b2b-payment-terms.md+++ b/docs/plans/6.0-6.1-b2b-payment-terms.md@@ -1,10 +1,10 @@# B2B Payment Terms, Deposits Schedule & Bank Transfer References-**Status:** Draft — design finalized 2026-08-30, nothing built-**Target:** Spree 6.0 (terms snapshot + fixes, riding the wholesale deposit work) / 6.1 (named terms, company assignment, bank transfer method, pay-balance)-**Depends on:** B2B Wholesale Shipping (6.0-b2b-wholesale-shipping.md — deposit collection, amended 2026-08-30), B2B Companies (6.0-b2b-companies-and-catalogs.md), Customer PO Numbers (6.0-b2b-customer-po-numbers.md), Document Numbers (6.0-document-numbers.md)+**Status:** Draft — nothing built. **Re-scoped 2026-09-07:** this plan is the single home for the whole subject — deposits, net terms and credit — after deposits were ruled out of scope for wholesale shipping (`decisions.md` 2026-09-07). It needs rewriting to cover both halves together, since they are two parts of one arrangement, before anything is built.+**Target:** Not scheduled. The 6.0 slot this plan assumed (riding the wholesale deposit work) no longer exists.+**Depends on:** B2B Companies (6.0-b2b-companies-and-catalogs.md), Customer PO Numbers (6.0-b2b-customer-po-numbers.md), Document Numbers (6.0-document-numbers.md)**Author:** Damian + Claude-**Last updated:** 2026-08-30+**Last updated:** 2026-09-07 (deposits removed from the wholesale-shipping plan; this plan owns the subject end to end and is unscheduled pending a rewrite that covers net terms too)## Summary@@ -27,22 +27,24 @@ credit is the commercial instrument (decided 2026-08-30).## Key Decisions (do not deviate without discussion)-- **One `payment_terms` snapshot on the order, layered sources**- (2026-08-30, interactive review — amends the wholesale plan): the cart- resolves `{kind, deposit_percentage, balance_due_label, source}` from- **quote/order override → company terms → the freight method's deposit- preferences → none (pay in full)** and the order freezes the copy at- placement — agreed terms survive later changes to the company default,- exactly like negotiated prices. The wholesale plan's method-level- `deposit_percentage` is demoted from anchor to *default source*;- `Cart#amount_due_at_checkout` now reads the snapshot. Same resolution- shape as `capture_method`.-- **`Spree::PaymentTerm` is a store-scoped named preset** (6.1): `name`- ("40% Deposit / 60% Before Shipping"), `kind` (`prepaid | deposit` — a- `class_attribute` vocabulary Enterprise extends with `net`),- `deposit_percentage`, `balance_due_label`. Companies reference one- (`payment_term_id`, nullable); the order snapshot copies **values, never- the reference** — a renamed preset must not rewrite history.+- **One `payment_terms` snapshot on the order** (2026-08-30, interactive+ review — amends the wholesale plan; **resolution narrowed 2026-09-07**):+ the cart resolves `{kind, deposit_percentage, balance_due_label, source}`+ and the order freezes the copy at placement — agreed terms survive later+ changes to the company's arrangement, exactly like negotiated prices.+ `Cart#amount_due_at_checkout` reads the snapshot.+- **Terms resolve from the buying company, and open source resolves+ nothing** (2026-09-07, interactive review — supersedes the layered chain+ above and the wholesale plan's method-level fields; see+ `decisions.md` 2026-09-07). `Spree::PaymentTerms.from_company` is the+ single point terms enter the system and answers nil in open source, so+ every purchase there owes its full total. A deposit is negotiated with a+ buyer, so the arrangement belongs to the company — not to the shipping+ method, which no comparable platform uses for this and which cannot+ express "this buyer, these terms" at all. The 6.0 preset model and+ `spree_companies.payment_term_id` are **removed**: an unreachable table+ configuring a feature open source does not expose earns no place in it.+ The quote/order override stays 6.1.- **The balance-due moment is a label, not automation** (the merchant's ownframing): `balance_due_label` ("Before shipping", "Before dispatch") isrecorded and displayed; real due *dates* arrive with Enterprise net@@ -93,7 +95,8 @@ credit is the commercial instrument (decided 2026-08-30).- `Carts::Complete` validates payments against `amount_due_at_checkout`(already the wholesale design — unchanged, just re-sourced); theinvoice-later `payment_pending:` path composes as before.-- Company: `payment_term_id` on `spree_companies` (admin form + serializer);+- Company: where the arrangement is read from — nothing in open source, which+ advertises the feature on the company profile instead;Enterprise's quote flow writes the order-level override(`b2b-quotes.md` shows terms on the quotation and acceptance freezesthem via placement — no quote-side fields).@@ -104,12 +107,24 @@ credit is the commercial instrument (decided 2026-08-30).## Migration Path-1. **6.0** (with wholesale phase 7): `payment_terms` jsonb + resolution- (method source only), `amount_due_at_checkout` re-sourced, schedule- value object + serializers; the `number` ransack/Stripe lookup fixes- (fixes shipped early, 2026-08-30, with the negotiation mechanics).-2. **6.1**: `Spree::PaymentTerm` + company assignment + dashboard settings- page; snapshot source layering completed; `PaymentMethod::BankTransfer`;+1. **Unscheduled** — the deposit engine (`payment_terms` snapshot, schedule+ value object + serializers, `partially_paid`) lands with the rest of this+ plan, not before. Shipping it alone gives a vocabulary with no way to set+ it, and leaves net terms — the other half of the same arrangement —+ without a home.++ **The attachment point is already in core**, so this plan starts from a+ hook rather than from patching: `Purchase#amount_due_at_checkout` answers+ the full total via `Spree::Purchases::AmountDueAtCheckout`, registered+ through `Spree::Dependencies`, and the four decisions that gate on money+ arriving (checkout requirements, both completion guards, dispatch)+ already read it. Terms resolution replaces that service; it does not+ rewrite the call sites.++ The `number` ransack/Stripe lookup fixes did ship early (2026-08-30, with+ the negotiation mechanics) and are unaffected.+2. **6.1**: the remaining snapshot source layer (quote/order override);+ `PaymentMethod::BankTransfer`;payment `reference` column + generation + search; store pay-balanceroute + storefront balance UI.diff --git a/docs/plans/6.0-b2b-wholesale-shipping.md b/docs/plans/6.0-b2b-wholesale-shipping.mdindex b3d891805d..252beb9321 100644--- a/docs/plans/6.0-b2b-wholesale-shipping.md+++ b/docs/plans/6.0-b2b-wholesale-shipping.md@@ -1,10 +1,10 @@# B2B Wholesale Shipping (Cartons, Pallets, Containers)-**Status:** Draft — design finalized 2026-08-30, nothing built+**Status:** Implemented — design finalized 2026-08-30; **phases 1–6 implemented 2026-08-31** (measurement helper, package types, carton chain, freight summary, volume/company rules, freight provider + unpriced rates, with the admin and store API surfaces); **phases 8–9 implemented 2026-09-05** (dashboard, storefront). **Phase 7 (deposits) is out of scope** — see the decision below.**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-09-03 (cross-reference to `6.0-shipping-labels-and-deliveries.md`: freight tracking rows, BOL never a label)+**Last updated:** 2026-09-07 (deposits are out of scope — how a buyer pays is its own subject with its own plan)## Summary@@ -15,8 +15,7 @@ by a forwarder *after* the merchant reviews the order, not calculated atcheckout. What the platform must do is different from parcel shipping: know howproducts pack into cartons, roll a cart up into logistics numbers (cartoncount, cubic meters, gross weight), classify the shipment into the right-merchant-configured tier, let checkout complete without a shipping price, and-collect the deposit the merchant's terms require for that shipment type.+merchant-configured tier, and let checkout complete without a shipping price.This plan adds that layer without touching retail shipping, so one catalog canserve both retail and wholesale buyers: a store-scoped **`Spree::PackageType`**@@ -26,12 +25,12 @@ reference to a carton-kind `PackageType` plus `units_per_carton` and packedgross weight), a **freight summary** rollup computed on the existing (currentlyunused) `Stock::Package#volume` chain, a **`DeliveryMethodRules::VolumeRule`**so shipment tiers are configuration on delivery methods rather than code,-**unpriced delivery rates** — a first-class "freight quoted after review" rate-carrying the logistics summary instead of a price — and **deposit collection at-checkout**: a freight method can require an N% deposit, the buyer pays exactly-that at completion, and the order tracks the outstanding balance until the-merchant settles it (including the freight `Fee` added once the forwarder-quotes).+and **unpriced delivery rates** — a first-class "freight quoted after review"+rate carrying the logistics summary instead of a price.++**What this plan deliberately does not cover:** how a wholesale buyer *pays*.+Deposits, net terms and credit limits are one subject and belong in one plan+of their own — see the decision below.## Key Decisions (do not deviate without discussion)@@ -41,8 +40,13 @@ quotes).replaces the four `default_package_*` store preferences — the store'sdefault shipping box becomes the store's default `PackageType` row (onedefault per store), read through the existing single access point- (`Stock::Package#weight`/`#dimensions`), with the preferences kept as- deprecated one-release bridges. The name is deliberately NOT+ (`Stock::Package#weight`/`#dimensions`). **The preferences are deleted+ outright, with no deprecation bridge** (2026-08-31, interactive review —+ a recorded exception to the always-bridge convention): they were added in+ this same unreleased 6.0 cycle, so there is no released API to keep+ working, and a bridge writing through to a row would leave two spellings+ of the store's box for one release with nothing gained. The name is+ deliberately NOT`Spree::Package`: `Spree::Stock::Package` is the in-memory packing unit atthe heart of the estimator, and a persisted sibling with the same namewould be permanently confusing.@@ -70,21 +74,47 @@ quotes).copy instead of a price. A zero-cost rate rendering as "Free" is amerchant-facing lie, and 6.0 is the window to model this properly insteadof blessing the placeholder-rate workaround.-- **Deposits are collected, not just displayed** (2026-08-30, interactive- review — the ambitious option, chosen deliberately): a freight method's- `deposit_percentage` changes what checkout charges. The buyer pays exactly- the deposit at completion; the order completes with an outstanding balance- and a partial payment status. This opens a partial-payment surface on- orders — scoped below to the minimum that makes deposits real (deposit- math in `Carts::Complete`, balance tracking via the existing- `outstanding_balance`, settlement through existing payment endpoints).- Anything beyond that (installment schedules, automatic balance capture,- dunning) is explicitly out of scope.-- **Deposit base = the order total at placement.** That total cannot include- the freight charge (it isn't quoted yet); the later freight `Fee` simply- increases the outstanding balance. One base, no second "deposit-eligible- subtotal" vocabulary; revisit only if real merchants need a- goods-only base.+- **Deposits are out of scope** (2026-09-07, interactive review —+ superseding the 2026-08-30 "deposits are collected" decision). This plan+ is about how wholesale goods *ship*: how they pack, how a cart rolls up+ into the numbers a forwarder quotes against, which tier a shipment falls+ into, and how a rate says its price is still to come. **How the buyer pays+ is a different subject.**++ Deposits (part payment now) and net terms (pay later) are two halves of+ one arrangement — merchants commonly combine them, "40% deposit, balance+ Net 30" — so answering half of it inside a shipping plan produces a+ vocabulary with no way to set it and no home for the other half. In+ particular a delivery method must not carry a `deposit_percentage`: the+ arrangement is negotiated with a buyer, not attached to how the goods+ travel. Partial payments themselves are untouched — they predate this work+ and remain generally available.++ **What this plan does leave is the extension point**, so the plan that+ owns the subject has somewhere to attach. `Purchase#amount_due_at_checkout` answers+ the whole total through {Spree::Purchases::AmountDueAtCheckout}, replaceable+ through `Spree::Dependencies`; four decisions read it rather than `total` —+ checkout requirements, both completion guards, and dispatch. Those are the+ places that ask "has enough money arrived?", and they are what an+ arrangement collecting part of the total up front would otherwise have to+ patch one by one. Everything else — what a new payment or gateway session+ *defaults* to, and the capture loop — still reads `total`, because those+ are amounts rather than decisions and a caller passes an explicit figure.++ Deposits, net terms and credit limits belong together in a payment-terms+ plan of their own, which does not yet exist. Two OSS plans already defer to+ it (`6.0-payment-method-rules.md`, `6.0-6.1-b2b-payment-terms.md`) and the+ Enterprise tier table records the boundary.++ **`DeliveryRateProvider::Freight` keeps only the unpriced rate**, which was+ always its real subject; the deposit readers were a second idea living in+ the same class.+- **An unset variant `dimensions_unit` follows the store's unit system**+ (2026-08-31, interactive review): imperial reads as inches, metric as+ centimeters. No new store preference — `unit_system` already decides what+ the store's box dimensions mean, and a second settable value could+ contradict it. This mirrors `weight_unit`'s fallback in shape, not in+ mechanism, because there is no `default_dimensions_unit` to mirror.- **Volume math is unit-aware from day one.** CBM derived from inchdimensions differs from centimeter math by a factor of ~16 — theraw-number shortcut `WeightRule` was allowed@@ -94,7 +124,8 @@ quotes).- **The freight summary on a completed order is frozen, never re-derived.**The summary the provider computes at estimate time is persisted in theselected `DeliveryRate#metadata` (jsonb, already exists); order-facing- reads come from there. Carts compute live. Same doctrine as the duty+ reads come from there, on carts and orders alike — a purchase with no+ selected freight rate reports no summary. Same doctrine as the dutysnapshot in `6.0-duties-and-custom-fees.md` — never re-derive logisticsfrom the live catalog on an existing order.- **The quoted freight charge is a `Fee`.** After the merchant gets the@@ -135,10 +166,14 @@ end(conditional UPDATE, partial index) — the same pattern as `CompanyAddress`defaults. `Stock::Package#weight` (tare) and `#dimensions` read the defaultrow instead of the four store preferences, so the EasyPost parcel path is- unchanged in shape; the preferences become deprecated one-release bridges- reading through the row.-- A backfill task creates the default row per store from the current- preference values (skipping stores still on the seeded zeros).+ unchanged in shape. The preferences themselves are removed outright — see+ the decision above; the upgrade task below is what carries their values+ over.+- An upgrade task (`spree:upgrade:package_types`) creates the default row+ per store from the preference values before they are dropped, skipping+ stores still on the seeded zeros. It runs before the migration that+ removes the preference keys, and is what makes deleting them safe without+ a bridge.- `carton` rows are what variants reference (below). `pallet`/`container`rows are merchant vocabulary and reference data (and the natural anchor forfuture label/BOL work); nothing in the tier math depends on them — tiers@@ -260,10 +295,18 @@ always CBM (unit-aware), never a raw column sum. Registered in the engine +i18n + dashboard Conditions card like the existing rules.`DeliveryMethodRules::CompanyRule` gates by buyer context: `preference-:company_presence, :string` (`required` | `absent`). `required` on freight-methods hides them from retail carts; `absent` on parcel methods hides those-from B2B carts where a merchant wants a hard split. It reads-`package.owner.b2b?` (company resolution already lives on the cart).+:company_orders_only, :boolean, default: true`. On, a freight method is+hidden from retail carts; off, a parcel method is hidden from B2B carts+where a merchant wants a hard split. It reads `package.owner.b2b?` (company+resolution already lives on the cart).++**A boolean, not a `required | absent` string** (2026-09-05, interactive+review): the rule has exactly two sides, and a string spelling them made the+dashboard render a free-text box for what is a switch — a preference type+carries its own UI, so the type has to be the honest one. The third state+the string allowed (unset = unconstrained) is not lost but relocated:+*having no company rule* is what leaves a method open to both, which is+where that meaning belonged.Per-company narrowing stays Enterprise territory — OSS gates on presenceonly, consistent with the no-company-roles stance.@@ -275,8 +318,7 @@ a `VolumeRule` range + `CompanyRule`(required), on the freight rate provider.- `Spree::DeliveryRateProvider::Freight` ships in core beside `Internal`.`estimates(package)` returns one `Estimate` with `unpriced: true`, `cost:- 0`, the method's name, and `metadata` = the freight summary plus the- method's deposit terms (below).+ 0`, the method's name, and `metadata` = the freight summary.- `Estimate` gains `unpriced` (boolean attribute); `spree_delivery_rates`gains an `unpriced` boolean column (default false). The estimator skipsmarkup for unpriced estimates and keeps its cheapest-first sort (cost is@@ -288,67 +330,21 @@ a `VolumeRule` range + `CompanyRule`(required), on the freight rate provider.- Completion snapshot: the winning rate row already persists `metadata`, sothe frozen summary rides for free.-### Deposits and the outstanding balance--> **Amended 2026-08-30 (later the same day, payment-terms work):** the-> method-level deposit preferences below are demoted from anchor to-> **default source**. The order carries ONE resolved `payment_terms`-> snapshot (quote/order override → company terms → these method-> preferences → none), and `Cart#amount_due_at_checkout` reads the-> snapshot — see `6.0-6.1-b2b-payment-terms.md`. The collection mechanics-> in this section (completion validation, `partially_paid`,-> `outstanding_balance`) are unchanged; only where the percentage comes-> from is layered. Open question 1 (storefront balance payment) is-> resolved there too (6.1 pay-balance route).--Freight methods (via the provider) declare terms:--```ruby-preference :deposit_percentage, :decimal, default: nil, nullable: true # nil = pay in full-preference :payment_instructions, :string # "Bank / TT Transfer"-```--Mechanics, scoped to the minimum that makes deposits real:--- **`Cart#amount_due_at_checkout`** — the order total, unless the selected- delivery rate carries a `deposit_percentage`, in which case it is- `total × deposit_percentage / 100` (rounded with the currency). Computed,- never stored on the cart.-- **`Carts::Complete` charges the deposit.** The payment-sufficiency check in- the completion pipeline validates payments against- `amount_due_at_checkout` instead of the full total; the deposit terms- (percentage, base amount, instructions) are stamped into the selected- rate's metadata alongside the freight summary. The existing- `payment_pending:` (invoice-later) path is unchanged and composes — a- merchant can require a deposit online or invoice the whole thing.-- **Balance = the existing `Order#outstanding_balance`** (total minus- payments net of refunds — already how the returns rework left it). The- freight `Fee` added after quoting increases the total and therefore the- balance. No new balance column.-- **Payment status**: the `Orders::UpdateStatuses` rollup derives a partial- state (`partially_paid`) when payments cover more than zero but less than- the total. Dashboard order list + page surface it with the balance.-- **Settling the balance** happens through the payment surfaces that already- exist: the admin records/captures further payments on the order; the- balance invoice/email and a storefront "pay the balance" flow are follow-up- work (open question 1).-- **Explicitly out of scope**: installment schedules, automatic capture at a- later date, dunning, deposit forfeiture rules. `capture_method` semantics- are untouched — a deposit payment is an ordinary payment for a smaller- amount.-### Where the money happens, end to end-1. Buyer completes checkout on an unpriced freight rate, paying the deposit- (or nothing, on the invoice-later path).+1. Buyer completes checkout on an unpriced freight rate. The goods are paid+ for; the freight is not, because nobody has quoted it yet.2. Merchant reviews the order — the dashboard order page shows a Logistics- card (shipment type, units, cartons, CBM, gross weight, deposit terms,- outstanding balance) read from the rate metadata + order money.+ card (shipment type, units, cartons, CBM, gross weight) read from the+ rate metadata.3. Merchant gets the forwarder's quote and adds it as a `Fee` (kind`freight`) via `/admin/orders/:id/fees`; totals recompute through the- existing typed-adjustments path; the balance grows accordingly.-4. Merchant collects the balance per the method's payment instructions and- records/captures it; `Orders::UpdateStatuses` rolls the order to paid.+ existing typed-adjustments path, and the order owes the difference.+4. Merchant collects that balance through the payment surfaces that already+ exist; `Orders::UpdateStatuses` rolls the order to paid.++How a buyer might instead pay a deposit up front, or take the goods on net+terms, is the payment-terms plan's subject, not this one's.### API surface@@ -357,10 +353,10 @@ Mechanics, scoped to the minimum that makes deposits real:two new rules automatically; order serializer exposes`outstanding_balance` (if not already) + the partial payment status.- Store: cart and order serializers gain a `freight_summary` object- (nullable — null when no line carries carton data) and the cart exposes- `amount_due_at_checkout`; summaries are computed live on carts and read- from the selected rate's metadata on orders. Delivery rate serializer- gains `unpriced` and carries deposit terms in metadata.+ (nullable — null when no line carries carton data); summaries are computed+ read from the selected freight rate's metadata on carts and orders alike,+ so a parcel shipment carries none. The+ delivery rate serializer gains `unpriced`.## Migration Path@@ -370,28 +366,40 @@ Mechanics, scoped to the minimum that makes deposits real:`carton_weight` + `cartons_per_pallet` on `spree_variants` (around the`units_per_carton` `6.0-b2b-quantity-rules.md` already added);`unpriced` on `spree_delivery_rates`.-3. **PackageType** — model, backfill task (`spree:package_types:backfill`)+3. **PackageType** — model, upgrade task (`spree:upgrade:package_types`)creating default rows from the store preferences, `Stock::Package`- reading through the default row, preference deprecation bridges.+ reading through the default row, then the preferences removed outright+ (no bridge).4. **Rollups** — `FreightSummary`, unit-aware `Stock::Package#volume`.5. **Rules** — `VolumeRule` + `CompanyRule` (+ engine registration, i18n,dashboard Conditions card).6. **Freight provider + unpriced rates** — provider, estimator handling,serializers.-7. **Deposits** — `amount_due_at_checkout`, the `Carts::Complete`- payment-sufficiency change, `partially_paid` in the status rollup,- admin balance surfaces.+7. **Deposits** — ~~`amount_due_at_checkout`, the `Carts::Complete`+ payment-sufficiency change, `partially_paid` in the status rollup, admin+ balance surfaces~~. **Cut 2026-09-07** and moved to a payment-terms plan+ of its own; nothing from this phase ships here.8. **Dashboard** — package types settings page, variant carton section- (sheet + spreadsheet + CSV), order Logistics card with balance,- "quoted after review" rendering.-9. **Storefront** — freight summary on cart/checkout, unpriced rate copy,- deposit line at payment ("Due now: $X (40% deposit) · Balance: $Y").+ (sheet + spreadsheet + CSV), order Logistics card,+ "quoted after review" rendering. **The Settings → Store card that edited+ the four `default_package_*` preferences was removed with them in phase 3,+ so between phase 3 and this phase the store's shipping box is+ API-only.** That gap is the cost of dropping the preferences without a+ bridge; the settings page below is what closes it, and it should not ship+ far behind.+9. **Storefront** — freight summary on cart/checkout, unpriced rate copy.No data migration beyond the package-type backfill: carton fields startempty, and nothing changes for stores that never fill them.## Constraints on Current Work+- **How the buyer pays is not this plan's subject.** Deposits, net terms+ and credit limits belong together in a payment-terms plan of their own+ (2026-09-07). A delivery method must not grow a `deposit_percentage`, and+ freight must not become a second place payment arrangements are+ configured — that coupling was built here once and removed for exactly+ this reason.- **Never compute volume by multiplying raw dimension columns.** Allvolume/CBM math goes through the unit-aware helper; the raw-numbershortcut recorded for `WeightRule` does not extend to volume.@@ -408,9 +416,6 @@ empty, and nothing changes for stores that never fill them.- **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.-- **Nothing may assume payments cover the order total at completion.** Code- that reads "completed ⇒ paid in full" is wrong once deposits land; check- `payment_status` / `outstanding_balance`, not completion.- **Post-placement freight charges are Fees**, never delivery-rate edits orad-hoc money columns.- **A new variant attribute must be permitted in all three write paths** or@@ -418,22 +423,45 @@ empty, and nothing changes for stores that never fill them.- Tier/eligibility logic hooks only in the Estimator filter chain via rules(existing `6.0-delivery-method-rules.md` constraint).+## Known Gaps (found in review, deliberately not fixed here)++- **EasyPost's parcel weight now converts from the store's `weight_unit`,+ not its `unit_system`.** The old reading multiplied a metric store's+ weight as if it were grams; the new one asks the preference that actually+ says what weights mean. It is the correct reading and it makes the tare+ (converted the same way) add up, but a live store on `unit_system: metric`+ that never set `weight_unit` moves from grams to the `lb` default — a+ large rescale of its quotes. Needs a release note, not a code change:+ such a store was already mixing units, since its variant weights were read+ in the default unit everywhere else.++- **`freight_summary` is an unstructured object in the OpenAPI specs.** It+ serializes with a known shape, so a `$ref`'d `FreightSummary` schema would+ let clients validate it. Not done here: the specs are generated from the+ rswag integration specs, the property type comes from Typelizer, and all+ sixty-odd unstructured attributes across the v3 serializers (`metadata`+ included) work the same way. Giving this one a shared schema means changing+ how the generator derives types across all three API branches — shared+ documentation infrastructure, not this feature.++- **Content weights are still summed across units.** `Package#weight` now+ converts the packaging tare into the store's weight unit, but+ `Stock::ContentItem#weight` sums `variant.weight * quantity` raw, and+ `Variant#weight_unit` falls back per variant — so a variant stored in+ grams and one in pounds are added together unconverted. This predates the+ plan and affects `WeightRule`, the weight splitter's threshold and the+ EasyPost parcel weight; `Spree::Measurement` is now in place to fix it, but+ the change touches every weight consumer and belongs in its own pass.+## Open Questions-1. **Storefront balance payment.** Should 6.0 ship a customer-facing "pay- the remaining balance" flow (account order page + payment session on the- balance), or is admin-recorded settlement enough for the first release?- Unblocked by: implementing phase 7 and seeing what the B2B storefront- purchasing work (spree/storefront#214 line) needs.-2. **Deposit rounding + tiny balances.** Currency rounding of- `total × percentage` can strand a cent of balance; decide the rounding- rule (round deposit up, absorb remainder into balance) during phase 7.+None. Both were resolved on 2026-09-05 — see Key Decisions.## References- Merchant feedback, 2026-08 (wholesale carton/pallet/container shippingwith freight quoted after review; logistics summary as the checkout- output; deposit percentage per shipment type).+ output).- `docs/plans/6.0-delivery-method-rules.md` — rules pattern + Estimator-onlyeligibility constraint.- `docs/plans/6.0-delivery-rate-provider.md` — provider contract the freight@@ -442,8 +470,7 @@ empty, and nothing changes for stores that never fill them.doctrine + the three-places variant attribute constraint.- `docs/plans/6.0-b2b-companies-and-catalogs.md` — company on cart,`#b2b?` / `resolved_company`.-- `docs/plans/6.0-service-workflows.md` — `Carts::Complete` pipeline the- deposit check slots into.+- `docs/plans/6.0-service-workflows.md` — the `Carts::Complete` pipeline.- `docs/plans/6.0-b2b-quantity-rules.md` — MOQ / order multiples / purchaseunit built on the same packing chain.- `docs/plans/6.0-inventory-operations.md` — lot-level inventory (out ofdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex ede49dde5f..d7b5c5a614 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,10 +1,10 @@-## 2026-09-04: Catalog audiences are alternatives, not layers — a company buyer is never also priced by their customer group (V-3570)+## 2026-09-07: Deposits are not a shipping concern — how a buyer pays gets its own plan-**Context:** `Catalog.for_context` consults a buyer's customer groups only when the company axis came back empty, so a merchant who put a shared range on a dealer group's company node and each trade tier on a customer group got tier prices that never applied — every dealer paid retail, with the catalog active, the audience assigned and the percentage saved. The code said two things about whether that was intended: the plan and the resolver describe a fallback chain, while `Spree::Catalog`'s class comment said visibility across applicable catalogs is their union, which reads as both audiences being consulted. The reading had to be ruled before either could be documented.+**Context:** `6.0-b2b-wholesale-shipping.md` originally specified deposits as part of wholesale freight: a delivery method would carry a `deposit_percentage`, checkout would collect it, and the order would complete part-paid. Building it raised two questions that had to be answered before it could ship. Is a shipping method the right thing to hang a payment arrangement on? And does merchant-configurable deposit collection belong in open source at all? Researching the second answered the first.-**Decision:** The fallback chain is the intended behaviour and stays: the company subtree if any of its nodes carry a catalog, otherwise the customer's groups, otherwise the channel's default catalog. A buyer is on one agreement, resolved from the nearest party to them — layering a personal segment's prices on top of a company's negotiated ones would price one purchase under two agreements at once, and which won would depend on catalog position rather than on anything a merchant chose. Trade tiers over a company tree are expressed as company assignments: the shared range on the root, each tier's catalog on the member companies or divisions in that tier (one tier catalog carries as many assignments as the tier has members). That route already works and is what the union-within-an-audience plus nearest-node-first pricing was built for. Customer group assignments remain for buyers not purchasing for a company at all — a retail loyalty tier, a staff discount.+**Decision:** This plan covers how goods **ship**; how the buyer **pays** is a separate subject with its own plan. Three findings drove it. **Deposits and net terms are two halves of one arrangement** — merchants combine them ("40% deposit, balance Net 30"), and the only native implementation in the market models the deposit as an attribute *on* a payment term. Shipping half the subject inside a shipping plan leaves a vocabulary with no way to set it and no home for the other half. **The arrangement belongs to the buyer, not the shipment** — a deposit is negotiated with a company; no comparable platform configures one per shipping method, and every one that offers deposits scopes them per product, per customer, or per order. **Two OSS plans already defer net terms** to a payment-terms plan that does not exist (`6.0-payment-method-rules.md`, `6.0-6.1-b2b-payment-terms.md`), so the destination was already named — it just had not been written.-**Consequences:** No behaviour change; the fix is that the code and the dashboard now say so. The class comment is corrected (it was the only place claiming the two audiences combine), the `for_context` and pricing-resolver comments read "or failing that" rather than "then", and the fallback carries an inline note. The dashboard states the precedence where a merchant can act on it: help text under the audience picker when a customer group is chosen, and a standing note on the audience card and wizard step whenever a group assignment is present, pointing at the company route for tier pricing. The developer docs stop framing the three ways of reaching a buyer as combining and carry the tier recipe as a warning. Three examples in `catalog_spec.rb` lock the ruling — the group dropping out once a company catalog exists, the group still applying when none does, and the subtree union when the tier is a company assignment. What is *not* solved: nothing detects a catalog assigned only to groups whose members are all company buyers, so such a catalog is still silently unreachable; a reachability warning needs the buyer population and is a separate piece of work.+**Consequences:** No delivery method carries a `deposit_percentage`, and freight must not become a second place payment arrangements are configured. One piece is deliberately kept so the payment-terms plan starts from a hook rather than from patching: `Purchase#amount_due_at_checkout`, answering the full total through `Spree::Purchases::AmountDueAtCheckout` (registered in `Spree::Dependencies`), read by the four decisions that gate on money arriving — checkout requirements, both completion guards, and dispatch. Without it, an arrangement collecting part of the total up front has to patch those four independently. It ships with a spec proving the open-source answer is the total, and a spec registering a half-up-front replacement and proving checkout, completion and dispatch all follow it. What a new payment or gateway session *defaults* to, and the capture loop, still read `total`: those are amounts rather than decisions. Partial payments are untouched — they predate this work. A related fix rides along because it holds independently: dispatch now guards on `payment_total >= amount_due_at_checkout` rather than `paid?`, which required a positive total and so refused to ship a fully discounted or store-credit-paid order.## 2026-09-03: A return label buys the cheapest rate; the fulfillment's tracking becomes a read-through summary@@ -4764,6 +4764,49 @@ agreement to understand every part of it at once); skippable steps (a"create now" escape hatch competing with Next on every step).Plans amended: `6.0-catalog-agreement-rework.md` (phase 4 completed).+## 2026-08-31 — Wholesale shipping backend: the store's box becomes a row with no bridge, and unpriced rates carry the logistics instead of a price++Phases 1–6 of `6.0-b2b-wholesale-shipping.md` — everything below the+dashboard and the storefront. Three rulings other plans need.++**The four `default_package_*` store preferences are deleted outright, with+no deprecation bridge.** A recorded exception to the always-bridge+convention, and the reasoning is narrow enough to be worth stating so it is+not read as a precedent: those preferences were added inside this same+unreleased 6.0 cycle, so no released version exposes them and there is no+caller to keep working. A bridge writing through to the new default+`PackageType` row would have left two spellings of the store's shipping box+coexisting for a release, each able to disagree with the other in the+dashboard, in exchange for compatibility nobody can be relying on. The+upgrade task (`spree:package_types:backfill`) creates each store's default+row from the preference values, which is what makes the removal safe. The+convention still holds for anything that shipped: bridge it.++**An unset variant `dimensions_unit` follows the store's `unit_system`** —+imperial reads as inches, metric as centimeters — rather than gaining a+`default_dimensions_unit` store preference to mirror `weight_unit`'s+fallback. The store already answers "what do dimensions mean here" through+`unit_system`, which is what the box preferences and the EasyPost provider+have always read; a second settable value could contradict it, and the+merchant would have no way to tell which one a number obeyed.++**An unpriced rate is a rate with no price, not a rate priced at zero.**+`Spree::DeliveryRateProvider::Estimate` and `spree_delivery_rates` carry an+`unpriced` boolean; the estimator skips markup and tax gross-up for those+rows, and `DeliveryRate#free?` answers false for them so nothing renders+"Free" over a shipment whose cost is genuinely unknown. This is the+mechanism the plan's constraint points at — a zero-cost priced rate is the+workaround it exists to prevent. `Spree::FreightSummary` (units, cartons,+pallets, CBM, gross weight, `complete?`) rides in the estimate's metadata+and is frozen onto the selected rate at completion, never re-derived from+the live catalog afterwards.++Everything money-shaped stays for phase 7: deposits, the completion+payment-sufficiency change and the partial-payment order surfaces are not in+this cut. **Constraint unchanged and now load-bearing:** nothing may assume+a completed order is paid in full once phase 7 lands.++Plan: `6.0-b2b-wholesale-shipping.md` (phases 1–6 implemented).## 2026-09-02 — Order cancellation and approval history tables are dropped; the reason lives on the order@@ -5043,3 +5086,19 @@ database into the editor: the products endpoint would have to hand theeditor variant rows, and the count and empty-state logic would follow. Onemodel in one place, kept true by an idempotent job, was the smaller change.+## 2026-09-05 — A CSV names its carton rather than referencing one++Settled while building the wholesale plan's variant import.++**A CSV names its carton; it does not reference one.** A merchant's+spreadsheet says "Large carton", not a prefixed id, so the products import+resolves the carton by name — and resolves it through `store.package_types`,+so a name that matches another store's carton leaves the variant unpacked+rather than borrowing somebody else's measurements. The tax-category lookup+beside it is *not* store-scoped and was left alone: widening it is a+separate correctness fix with its own blast radius, not something to smuggle+into a packaging change.++**Constraint now:** a new named lookup in an importer resolves through the+store's own association.+