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 price-list CSV decisions in the volume pricing plan
Damian Legawiec426783927c7a
diff --git a/docs/plans/6.0-volume-pricing.md b/docs/plans/6.0-volume-pricing.mdindex e18add18ba..717634e52b 100644--- a/docs/plans/6.0-volume-pricing.md+++ b/docs/plans/6.0-volume-pricing.md@@ -1,7 +1,9 @@# Volume Pricing (Quantity Breaks + Banded Adjustments)**Status:** Implemented — schema, resolver, banded adjustment, Admin API and-both dashboard tier editors shipped 2026-09-07 (spree/spree#14589)+both dashboard tier editors shipped 2026-09-07 (spree/spree#14589); the+price-list CSV export/import, the fixed-tiers note and the tier-editor+end-to-end coverage followed the same day (follow-up PR)**Target:** Spree 6.0 — fully (2026-09-07: first the schema/resolver phases were pulled into the major because `min_quantity` changes the row identity of the released `spree_prices` table; then the whole plan followed — shipping the feature in one release is faster than splitting the UI off by a release boundary)**Depends on:** Catalog Agreement Rework (6.0-catalog-agreement-rework.md — implemented; owned lists + contextual rules), Price List Automatic Pricing (6.0-price-list-automatic-pricing.md — implemented; the ±% machinery this extends), B2B Quantity Rules (6.0-b2b-quantity-rules.md — the separate ordering axis)**Author:** Damian + Claude@@ -83,15 +85,35 @@ promotion territory and are deliberately deferred.existing `TieredPercent`) — recorded as the deferred design, not builthere. Contracted terms never render as discounts; marketing never hidesas pricing.-- **Price-list CSV is deferred, not shipped here** (2026-09-07,- implementation review): the plan assumed a price-list CSV import/export- that has never been built — the only price columns in any CSV today are- the product export's base `price`/`compare_at_price`. Adding- `min_quantity` to a surface that does not exist is not a column- addition, it is a whole import/export pipeline. When a price-list CSV is- built it carries `min_quantity` from its first version; the product CSV- is untouched, since breaks require a price list and every base row is- quantity 1 by construction.+- **Price-list CSV ships as a per-list export and a merge import**+ (2026-09-07, follow-up review — supersedes the same-day deferral): the+ plan had assumed a price-list CSV that never existed, so it is built here+ on the shipped export/import pipelines rather than as a column on the+ product CSV. Four calls, each with the cheaper alternative rejected:+ - **A row is keyed by SKU** — the same key the product CSV uses, and the+ file carries nothing else the import would not read (2026-09-08: the+ read-only `product`/`variant` columns first shipped were dropped, since a+ column that changes nothing on the way back reads as if it would). A+ variant without a SKU, or a SKU two sellers share, is refused row by+ row with a message.+ A prefixed `variant_id` fallback column was rejected as one more rule+ to explain for a case the product CSV does not cover either.+ - **An import merges** — rows in the file are written or updated, a row+ with a blank price removes that rung, and rungs the file does not+ mention stay as they are. Exactly the bulk editor's write semantics+ (`Prices::BulkUpsert`), so the two surfaces can never disagree. A+ "replace the whole list" mode was rejected: it needs a destructive+ confirm, and a half-failed import would leave a half-replaced list.+ - **The export writes priced rows only.** A placeholder row (on the list,+ no amount) is not written as a blank price, because re-importing an+ unchanged export would then remove those products from the list.+ - **Both homes**, like the tier editors: the buttons sit next to "Edit+ prices" on the price-list page and on the catalog's pricing card.+ - **A sample file ships** (`db/sample_data/price_list_prices.csv`) and+ sample data loads it onto the Wholesale list, so the example download+ in the import sheet is a working ladder rather than a header row.+ The product CSV is untouched: breaks require a price list, so every base+ row is quantity 1 by construction.- **The ≤10 cap is a model validation, scoped to`(variant, currency, price_list)`** (2026-09-07): an eleventh break isrefused with a message, and the bulk-upsert path refuses a batch that@@ -124,14 +146,16 @@ promotion territory and are deliberately deferred.editor (`[Min qty | Unit price]` rows, add/delete, strictly-increasingvalidation) — one component, reused on the catalog page'sproducts-with-prices view. The admin price endpoints + bulk upsert accept- `min_quantity`. Price-list CSV is deferred (see Key Decisions).+ `min_quantity`. The price-list CSV is a per-list export and a merge+ import on the same pipelines as the product CSV (see Key Decisions).- Storefront: no ladder display in v1 (the merchant's own preference) —the line's unit price re-resolves as quantity crosses thresholds. APDP "buy more, save more" widget is a later opt-in read of the samerows.-- Banded adjustment: the Pricing card (standalone list page + catalog- page) gains "Add quantity tier" rows under the existing- magnitude/direction controls — same tier-editor component as the fixed+- Banded adjustment: the catalog page's Pricing card gains "Add quantity+ tier" rows under the existing magnitude/direction controls — the catalog+ page only, since a percentage (and so a band) is refused on a standalone+ list (6.0-price-list-automatic-pricing.md) — same tier-editor component as the fixedbreaks; the resolution cache keys gain the quantity band the same waythe fixed-break path does.@@ -163,13 +187,14 @@ quantity-1 row.prices.- No coupling between quantity rules (MOQ/multiple) and price tiers.- Exports/feeds reading list prices must account for tier rows (a- quantity-1-only export silently drops the ladder).+ quantity-1-only export silently drops the ladder). The price-list CSV+ carries `min_quantity` and writes every rung.## Open QuestionsNone for this scope; the four raised at implementation time (2026-09-07)-are settled in Key Decisions above. Deferred, recorded: price-list CSV-import/export (carrying `min_quantity` when built); base-price (D2C)+are settled in Key Decisions above, as are the four the price-list CSV+raised. Deferred, recorded: base-price (D2C)tiers = one validation to lift; PDP ladder widget; the marketingvolume-discount promotion pair (`LineQuantity` rule + quantity-tieredpercent calculator); per-tier `kind: percent` on price rows (rejected —@@ -195,6 +220,11 @@ bands on the adjustment cover it with the implemented semantics).because three write paths reach that service and none of them run modelvalidations. Counted the same way in the model and the service: breaks abovethe ordinary price, placeholder rows not counted.+- The CSV import is one more caller of `Prices::BulkUpsert`, which is what+ makes a blank price mean "remove this rung" in the file exactly as it does+ in the editor. The one thing the service does not check is the sign of an+ amount — it trusts its callers — so the row processor refuses a negative+ or unparsable figure itself before handing the row over.- A band of exactly 0% is refused rather than stored: a factor of 1 makes thelist decline to price the line at all, so a band meaning "no furtherdiscount here" would fall through to the next list. Removing the band is howdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 6b7c71b4f3..93178950bb 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -4985,3 +4985,34 @@ everywhere — validating the existing quantity-rules split. Constraints:contracted tiers are never discounts, marketing discounts are neverprices; price-reading callers must pass line quantity through`Pricing::Context`; exports must carry tier rows.++## 2026-09-07 — Price-list CSV: SKU-keyed rows, a merge import, both homes, a sample ladder++Settled before building the follow-up to `6.0-volume-pricing.md`, which+had deferred the price-list CSV because no such surface existed.++**Rows are keyed by SKU**, as the product CSV's are, and the file carries+only the columns the import reads (2026-09-08: read-only `product` and+`variant` columns were dropped — a column that changes nothing on the way+back reads as if it would). A SKU-less variant or a SKU shared across+sellers fails its row with a message. A+prefixed `variant_id` fallback was rejected as a second rule for a case the+product CSV does not cover either.++**The import merges.** Rows in the file are upserted, a blank price removes+that rung, and rungs absent from the file are untouched — the bulk price+editor's semantics, reached through the same `Prices::BulkUpsert`. A+replace mode was rejected: destructive, and a half-failed import leaves a+half-replaced list. Consequence for the export: **placeholder rows are not+written** — a blank price on re-import would remove the product from the+list, so an unchanged export must re-import as a no-op.++**Both homes.** Export and import sit next to "Edit prices" on the+price-list page and on the catalog's pricing card, for the reason the tier+editors ship in both: a merchant editing an agreement should not have to+leave it.++**A sample file ships** in `db/sample_data` and sample data loads it onto+the Wholesale list — the import sheet's example download is then a real+ladder, and a fresh QA environment shows breaks without a script.+diff --git a/docs/user/how-to/volume-pricing.mdx b/docs/user/how-to/volume-pricing.mdxindex 6c06d4a5b2..c2b4a2b22e 100644--- a/docs/user/how-to/volume-pricing.mdx+++ b/docs/user/how-to/volume-pricing.mdx@@ -9,6 +9,8 @@ In Spree, you set this up using Price Lists with a Volume rule. Each pricing tieIn this guide, we'll set up two tiers: a mid-volume tier (21–50 units) and a high-volume tier (51–100 units).+<Note>A single price list can also carry per-variant **quantity breaks**: a lower unit price from a given quantity up, set in the price edit form or imported from a CSV. Use separate price lists, as below, when whole assortments or rules differ between tiers; use quantity breaks when the same list should simply charge less per unit at volume. See [Price Lists](/user/manage-products/price-lists#quantity-breaks).</Note>+<Note>This guide focuses on volume-based pricing. If you need to combine volume pricing with customer group or regional rules — for example, offering wholesale volume discounts only to registered trade customers — see [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) instead.</Note>## Prerequisitesdiff --git a/docs/user/manage-products/price-lists.mdx b/docs/user/manage-products/price-lists.mdxindex a791f75691..f00bd857b3 100644--- a/docs/user/manage-products/price-lists.mdx+++ b/docs/user/manage-products/price-lists.mdx@@ -78,6 +78,28 @@ Select which currency you'd like to update prices for, and update the values inOnce you’ve finished entering the custom prices, click **Save** to apply your changes.+### Quantity Breaks++A price list can charge less per unit from a given quantity up. In the price edit form, click **Add quantity break** under a variant, enter the quantity the break starts at and the unit price from that quantity, then **Save**. A variant can carry up to ten breaks per currency on one price list, and each break must start at a different quantity.++When a customer's order line reaches a break, the line is priced at that break's unit price. A variant with breaks is priced by its breaks alone: a catalog's percentage adjustment does not apply on top of them.++### Importing and Exporting Prices++Next to **Edit Prices** you'll find **Export** and **Import**, which move a price list's prices as a CSV file, one row per variant, currency and quantity break.++**Export** downloads every priced row of the list. **Import** merges a file into the list: each row in the file is written or updated, a row with a blank price removes that row from the list (the regular price or a break alike; a variant with no rows left is no longer on the list), and prices the file does not mention are left as they are. Rows the import cannot place are listed in the import report and do not stop the rest: an unknown SKU, a SKU shared by more than one variant, a currency the store does not sell in, a price that is not a plain number like `16.50`, a quantity that is not a whole number, or an eleventh break on one variant. Rows are applied one at a time, so to replace a variant's full set of ten breaks with new quantities, import the blank-price rows that clear the old breaks first, then the new ones.++| Field | Description |+| -------------------- | ----------------------------------------------------------------------------------------- |+| **sku** | The variant's SKU, matched regardless of letter case. Exactly one variant in the store may carry it |+| currency | The price's currency. Defaults to the store's default currency |+| min_quantity | The quantity the price applies from. Blank or `1` is the variant's regular list price |+| **price** | The unit price from that quantity, as a plain number like `16.50`. Leave blank to remove the row |+| compare_at_price | The optional non-marked-down price shown next to the unit price |++An exported file has exactly these columns, so it can be edited and imported back as it is. Download a working example from the import form.+## Activating the Price ListOnce everything is configured, go back to the price list editor, and click **Activate** in the top right corner.