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
Added regional-volume and regional-wholesale guides (#13796)
jaburghese43292a30307
diff --git a/docs/docs.json b/docs/docs.jsonindex 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.pngnew file mode 100644index 0000000000..dbc7ac89c7Binary files /dev/null and b/docs/images/user/how-to/regional-volume/1-new-price-list-form.png differdiff --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.pngnew file mode 100644index 0000000000..0bb9d4bf93Binary files /dev/null and b/docs/images/user/how-to/regional-volume/2-match-all-rules.png differdiff --git a/docs/images/user/how-to/regional-volume/3-edit-prices.png b/docs/images/user/how-to/regional-volume/3-edit-prices.pngnew file mode 100644index 0000000000..174f3fd3ecBinary files /dev/null and b/docs/images/user/how-to/regional-volume/3-edit-prices.png differdiff --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.pngnew file mode 100644index 0000000000..104cd5effdBinary files /dev/null and b/docs/images/user/how-to/regional-volume/4-edit-prices-eur.png differdiff --git a/docs/images/user/how-to/regional-wholesale/1-markets-configured.png b/docs/images/user/how-to/regional-wholesale/1-markets-configured.pngnew file mode 100644index 0000000000..7f968d72f5Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/1-markets-configured.png differdiff --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.pngnew file mode 100644index 0000000000..ef67829dd3Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/2-new-customer-group.png differdiff --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.pngnew file mode 100644index 0000000000..68526d5102Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/3-customer-group-created.png differdiff --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.pngnew file mode 100644index 0000000000..de4173a344Binary files /dev/null and b/docs/images/user/how-to/regional-wholesale/4-match-all-rules.png differdiff --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.pngnew file mode 100644index 0000000000..8904e4c37aBinary files /dev/null and b/docs/images/user/how-to/regional-wholesale/5-edit-prices-usd.png differdiff --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.pngnew file mode 100644index 0000000000..22c4d18e2cBinary files /dev/null and b/docs/images/user/how-to/regional-wholesale/6-edit-prices-eur.png differdiff --git a/docs/user/how-to/regional-volume.mdx b/docs/user/how-to/regional-volume.mdxnew file mode 100644index 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**.++++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`++++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.++++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++++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 Marketsdiff --git a/docs/user/how-to/regional-wholesale.mdx b/docs/user/how-to/regional-wholesale.mdxnew file mode 100644index 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`.++++## 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**.++++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.++++## 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**++++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.++++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++++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