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.

Added regional-volume and regional-wholesale guides (#13796)

jaburghese43292a30307
diff --git a/docs/docs.json b/docs/docs.json
index 9bff72deb7..ee719ad4e3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -556,7 +556,9 @@
"user/how-to/multi-currency-pricing",
"user/how-to/multi-region-pricing",
"user/how-to/wholesale-pricing",
- "user/how-to/volume-pricing"
+ "user/how-to/volume-pricing",
+ "user/how-to/regional-wholesale",
+ "user/how-to/regional-volume"
]
},
{
diff --git a/docs/images/user/how-to/regional-volume/1-new-price-list-form.png b/docs/images/user/how-to/regional-volume/1-new-price-list-form.png
new file mode 100644
index 0000000000..dbc7ac89c7
Binary files /dev/null and b/docs/images/user/how-to/regional-volume/1-new-price-list-form.png differ
diff --git a/docs/images/user/how-to/regional-volume/2-match-all-rules.png b/docs/images/user/how-to/regional-volume/2-match-all-rules.png
new file mode 100644
index 0000000000..0bb9d4bf93
Binary files /dev/null and b/docs/images/user/how-to/regional-volume/2-match-all-rules.png differ
diff --git a/docs/images/user/how-to/regional-volume/3-edit-prices.png b/docs/images/user/how-to/regional-volume/3-edit-prices.png
new file mode 100644
index 0000000000..174f3fd3ec
Binary files /dev/null and b/docs/images/user/how-to/regional-volume/3-edit-prices.png differ
diff --git a/docs/images/user/how-to/regional-volume/4-edit-prices-eur.png b/docs/images/user/how-to/regional-volume/4-edit-prices-eur.png
new file mode 100644
index 0000000000..104cd5effd
Binary files /dev/null and b/docs/images/user/how-to/regional-volume/4-edit-prices-eur.png differ
diff --git a/docs/images/user/how-to/regional-wholesale/1-markets-configured.png b/docs/images/user/how-to/regional-wholesale/1-markets-configured.png
new file mode 100644
index 0000000000..7f968d72f5
Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/1-markets-configured.png differ
diff --git a/docs/images/user/how-to/regional-wholesale/2-new-customer-group.png b/docs/images/user/how-to/regional-wholesale/2-new-customer-group.png
new file mode 100644
index 0000000000..ef67829dd3
Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/2-new-customer-group.png differ
diff --git a/docs/images/user/how-to/regional-wholesale/3-customer-group-created.png b/docs/images/user/how-to/regional-wholesale/3-customer-group-created.png
new file mode 100644
index 0000000000..68526d5102
Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/3-customer-group-created.png differ
diff --git a/docs/images/user/how-to/regional-wholesale/4-match-all-rules.png b/docs/images/user/how-to/regional-wholesale/4-match-all-rules.png
new file mode 100644
index 0000000000..de4173a344
Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/4-match-all-rules.png differ
diff --git a/docs/images/user/how-to/regional-wholesale/5-edit-prices-usd.png b/docs/images/user/how-to/regional-wholesale/5-edit-prices-usd.png
new file mode 100644
index 0000000000..8904e4c37a
Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/5-edit-prices-usd.png differ
diff --git a/docs/images/user/how-to/regional-wholesale/6-edit-prices-eur.png b/docs/images/user/how-to/regional-wholesale/6-edit-prices-eur.png
new file mode 100644
index 0000000000..22c4d18e2c
Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/6-edit-prices-eur.png differ
diff --git a/docs/user/how-to/regional-volume.mdx b/docs/user/how-to/regional-volume.mdx
new file mode 100644
index 0000000000..07b0a900ae
--- /dev/null
+++ b/docs/user/how-to/regional-volume.mdx
@@ -0,0 +1,103 @@
+---
+title: "Set Up Regional Volume Pricing"
+description: "Learn how to offer market-specific volume discounts across multiple regions using Price Lists in Spree Commerce."
+---
+
+Regional volume discounts let you offer quantity-based price breaks that are specific to each market. For example, a customer ordering 25 units in the US sees a USD discount, while a customer ordering the same quantity in Germany sees the equivalent EUR discount — and the thresholds and rates can differ by market too.
+
+In Spree, you do this by combining a Market rule and a Volume rule on each Price List using **Match All** logic. Each market gets its own set of tiered price lists, and Spree applies the correct one based on where the customer is shopping and how many units they're ordering.
+
+In this guide, we'll set up two volume tiers for each of three markets: US (USD), Germany (EUR), and France (EUR).
+
+<Note>This guide assumes your DE and FR markets are already configured and your products have EUR base prices set. If not, follow [<u>Set Up Multi-Currency Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-currency-pricing) first. For volume pricing without a regional split, see [<u>Set Up Volume Pricing</u>](https://spreecommerce.org/docs/user/how-to/volume-pricing). For regional wholesale pricing using Customer Group rules, see [<u>Set Up Regional Wholesale Pricing</u>](https://spreecommerce.org/docs/user/how-to/regional-wholesale).</Note>
+
+## Prerequisites
+
+Before you start, you should have:
+
+- Markets configured for US, Germany, and France, with EUR base prices set on all products you want to include. See [<u>Set Up Multi-Currency Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-currency-pricing) for the full walkthrough.
+- A clear set of volume thresholds and discounted prices for each market and tier.
+
+Familiarity with Price Lists and volume rules is helpful. See [<u>Set Up Volume Pricing</u>](https://spreecommerce.org/docs/user/how-to/volume-pricing) for a full walkthrough of the volume rule setup.
+
+## Overview
+
+You'll be creating six price lists in total — two tiers for each of the three markets:
+
+| Price List | Market | Volume Rule | Currency |
+|---|---|---|---|
+| US Volume (21–50 Units) | United States | Min: 21, Max: 50 | USD |
+| US Volume (51–100 Units) | United States | Min: 51, Max: 100 | USD |
+| Germany Volume (21–50 Units) | Germany | Min: 21, Max: 50 | EUR |
+| Germany Volume (51–100 Units) | Germany | Min: 51, Max: 100 | EUR |
+| France Volume (21–50 Units) | France | Min: 21, Max: 50 | EUR |
+| France Volume (51–100 Units) | France | Min: 51, Max: 100 | EUR |
+
+## 1. Create Volume Price Lists for the US Market
+
+Navigate to **Products → Price Lists** and click **New Price List**.
+
+![The New Price List form in Spree Commerce](/docs/images/user/how-to/regional-volume/1-new-price-list-form.png)
+
+Fill in the details for the first US tier:
+
+- **Name** — e.g., `US Volume Pricing (21–50 Units)`
+- **Description** — optional (e.g., `Mid-volume USD discount for US market`)
+- **Start Date / End Date** — leave blank to apply indefinitely
+
+Click **Create** to open the price list editor.
+
+In the Rules section, set the match logic to **Match All**, then add two rules:
+
+1. Click **Add Rule**, select **Market**, and choose **United States**
+2. Click **Add Rule** again, select **Volume**, and set **Min Quantity** to `21` and **Max Quantity** to `50`
+
+![The price list editor showing Match All logic with a Market rule and a Volume rule](/docs/images/user/how-to/regional-volume/2-match-all-rules.png)
+
+Click **Add Products**, select the products to include, then click **Edit Prices**. Make sure **USD** is selected in the currency switcher and enter the discounted USD prices for this tier.
+
+![The price editor showing discounted USD prices for the US 21–50 unit tier](/docs/images/user/how-to/regional-volume/3-edit-prices-usd.png)
+
+Click **Save**, then **Activate** (or **Schedule** if it has a future start date) to make this tier live.
+
+Now repeat to create the second US tier — `US Volume Pricing (51–100 Units)` — with the same Market rule (United States) and a Volume rule set to **Min: 51, Max: 100**. Enter the deeper discounted USD prices and activate.
+
+## 2. Create Volume Price Lists for Germany and France
+
+With the US tiers in place, repeat the same process for Germany and France. For each market you'll create two price lists — one per volume tier.
+
+For each price list:
+
+- Name it clearly, e.g., `Germany Volume Pricing (21–50 Units)` and `Germany Volume Pricing (51–100 Units)`
+- Set **Match All** with a **Market** rule targeting the correct market and a **Volume** rule with the appropriate min/max quantities
+- When editing prices, make sure **EUR** is selected in the currency switcher and enter the regional EUR discounts for each tier
+
+![The price editor showing discounted EUR prices for the Germany 21–50 unit tier](/docs/images/user/how-to/regional-volume/4-edit-prices-eur.png)
+
+Click **Save** and **Activate** for each. Once done, you'll have six active price lists — two tiers for each of the three markets.
+
+<Note>Volume thresholds and discount rates don't need to match across markets. You can set different min/max quantities or different discount levels for each region to reflect local pricing strategies or distribution agreements.</Note>
+
+## 3. Verify on the Storefront
+
+To confirm the tiers are working correctly, test from the storefront across each market.
+
+1. Visit your storefront and switch to the **United States** market.
+2. Add a product to the cart, set the quantity to `25`, and confirm the mid-volume USD discount is applied at checkout.
+3. Update the quantity to `60` and confirm the deeper USD discount applies.
+4. Switch to the **Germany** market, repeat the quantity tests, and confirm the correct EUR discounts appear.
+5. Repeat for the **France** market.
+
+If the expected discount is not being applied, check that:
+
+- The price list is set to **Active**
+- Both rules (Market and Volume) are present and set to **Match All**
+- The quantity in the cart falls within the min–max range of the relevant tier
+- The correct currency is set on the prices in the price list editor
+
+## Next Steps
+
+- [<u>Set Up Volume Pricing</u>](https://spreecommerce.org/docs/user/how-to/volume-pricing) — volume discounts without a regional split
+- [<u>Set Up Regional Wholesale Pricing</u>](https://spreecommerce.org/docs/user/how-to/regional-wholesale) — combine market and customer group rules for regional wholesale pricing
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, match logic, and price editing
+- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring Markets
diff --git a/docs/user/how-to/regional-wholesale.mdx b/docs/user/how-to/regional-wholesale.mdx
new file mode 100644
index 0000000000..efe43ec97e
--- /dev/null
+++ b/docs/user/how-to/regional-wholesale.mdx
@@ -0,0 +1,125 @@
+---
+title: "Set Up Regional Wholesale Pricing"
+description: "Learn how to offer market-specific wholesale pricing to trade customers across multiple regions."
+---
+
+Regional wholesale pricing lets you show different contracted prices to wholesale buyers depending on which market they're shopping in. For example, a US wholesale customer sees USD wholesale prices, while a German wholesale customer sees EUR wholesale prices — and both see prices different from what a standard retail customer would see.
+
+In Spree, you do this by combining a Customer Group rule and a Market rule on each Price List, using **Match All** logic. This means the price list only applies when a customer belongs to the wholesale group *and* is browsing in the correct regional market.
+
+In this guide, we'll set up regional wholesale pricing for a US-based store expanding into Germany and France, with dedicated wholesale tiers for all three markets.
+
+## Prerequisites
+
+Before you start, you should have your products set up with base USD prices. If you're new to multi-currency or wholesale pricing in Spree, it's worth reading these first:
+
+- [<u>Set Up Multi-Currency Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-currency-pricing) — how to create markets and set base prices per currency
+- [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — how to create customer groups and price lists with a Customer Group rule
+
+## 1. Create Markets for Germany and France
+
+Each region needs its own Market before you can target it with a regional price list. If your DE and FR markets are already set up, skip to [Step 2](#2-assign-eur-base-prices-to-your-products).
+
+Navigate to **Settings → Markets** and click **New Market**. Create the Germany market first:
+
+- **Name** — `Germany`
+- **Default Country** — `Germany`
+- **Currency** — `EUR`
+- **Default Locale** — `DE` or `EN`
+- **Tax Inclusive** — check this for standard EU VAT-inclusive pricing
+- **Default** — leave unchecked
+
+Click **Create**, then repeat to create the France market with **Default Country** set to `France` and **Default Locale** to `FR` or `EN`.
+
+![The Markets overview showing US (USD), Germany (EUR), and France (EUR) markets configured](/docs/images/user/how-to/regional-wholesale/1-markets-configured.png)
+
+## 2. Assign EUR Base Prices to Your Products
+
+With EUR markets in place, you'll need to set a base EUR price on every product you want to sell in Germany and France. These base prices are what standard retail customers in those markets will see — your wholesale price lists will override them for wholesale buyers.
+
+Navigate to **Products**, open each product, and use the currency switcher in the **Pricing** or **Variants** section to enter the EUR base price. See [<u>Set Up Multi-Currency Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-currency-pricing#2-set-eur-prices-on-your-products) for the full walkthrough.
+
+<Warning>Any product without a EUR base price will not appear to customers browsing in the Germany or France markets, including your wholesale buyers. Make sure base EUR prices are set before creating your wholesale price lists.</Warning>
+
+## 3. Create a Wholesale Customer Group
+
+You'll need a single Customer Group to represent all your wholesale buyers across all regions. A single group works here because the regional split is handled by the Market rule on each price list — not by separate groups.
+
+Navigate to **Customers → Customer Groups** and click **New Customer Group**.
+
+![The New Customer Group form in Spree Commerce](/docs/images/user/how-to/regional-wholesale/2-new-customer-group.png)
+
+Fill in the details:
+
+- **Name** — e.g., `Wholesale Buyers`
+- **Description** — optional (e.g., `Registered trade accounts across all markets`)
+
+<Note>Alternatively, you could set up different Customer Groups for each market.</Note>
+
+Click **Create**, then click **Add Customers** to add your wholesale accounts to the group. Repeat as you onboard new trade customers.
+
+![A Wholesale Buyer customer group in Spree Commerce](/docs/images/user/how-to/regional-wholesale/3-customer-group-created.png)
+
+## 4. Create a Wholesale Price List for Each Market
+
+You'll now create three price lists — one per market. Each will use **Match All** logic with two rules: a Customer Group rule targeting **Wholesale Buyers**, and a Market rule targeting the relevant market. This combination ensures the price list only activates for wholesale customers in that specific region.
+
+### US Wholesale Price List
+
+Navigate to **Products → Price Lists** and click **New Price List**.
+
+- **Name** — e.g., `US Wholesale Pricing`
+- **Description** — optional (e.g., `USD wholesale prices for US trade accounts`)
+- **Start Date / End Date** — leave blank to apply indefinitely
+
+Click **Create** to open the price list editor.
+
+In the Rules section, set the match logic to **Match All**, then add two rules:
+
+1. Click **Add Rule**, select **Customer Group**, and choose **Wholesale Buyers**
+2. Click **Add Rule** again, select **Market**, and choose **United States**
+
+![The price list editor showing Match All logic with a Customer Group rule and a Market rule](/docs/images/user/how-to/regional-wholesale/4-match-all-rules.png)
+
+Click **Add Products**, select the products to include, then click **Edit Prices**. Make sure **USD** is selected in the currency switcher and enter the wholesale USD prices in the **Price** column.
+
+![The price editor showing USD wholesale prices for the US market](/docs/images/user/how-to/regional-wholesale/5-edit-prices-usd.png)
+
+Click **Save**, then click **Activate** (or **Schedule** if it has a future start date) to make the price list live.
+
+### Germany and France Wholesale Price Lists
+
+Repeat the same process for Germany and France. For each:
+
+- Name them clearly — e.g., `Germany Wholesale Pricing` and `France Wholesale Pricing`
+- Set **Match All** with a **Customer Group** rule (Wholesale Buyers) and a **Market** rule targeting the correct market
+- When editing prices, make sure **EUR** is selected in the currency switcher and enter the regional EUR wholesale prices
+
+![The price editor showing EUR wholesale prices for the Germany market](/docs/images/user/how-to/regional-wholesale/6-edit-prices-eur.png)
+
+Click **Save** and **Activate** for each.
+
+<Note>Wholesale prices don't need to be the same across markets. You can set independent EUR prices for Germany and France — for example, to account for local market conditions or distributor agreements.</Note>
+
+## 5. Verify Pricing
+
+To confirm the setup is working correctly, log in to your storefront using a customer account that belongs to the Wholesale Buyers group.
+
+1. Switch to the **United States** market and confirm wholesale USD prices are displayed on your products.
+2. Switch to the **Germany** market and confirm wholesale EUR prices are shown.
+3. Switch to the **France** market and confirm the France-specific EUR wholesale prices are shown.
+4. Log out and repeat the market checks as a guest — you should see standard retail prices across all three markets.
+
+If wholesale prices are not appearing, check that:
+
+- The customer account is added to the **Wholesale Buyers** group
+- The price list is set to **Active**
+- Both rules (Customer Group and Market) are present and set to **Match All**
+- The correct currency is set on the prices in the price list editor
+
+## Next Steps
+
+- [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — wholesale pricing without regional splits
+- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — regional pricing without a wholesale overlay
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, match logic, and price editing
+- [<u>Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring Markets