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 more How-to pricing guides (#13787)

jaburghesacca087849a7
diff --git a/docs/docs.json b/docs/docs.json
index efb68a0367..afc13efbb7 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -555,7 +555,9 @@
"group": "How-to Guides",
"pages": [
"user/how-to/multi-currency-pricing",
- "user/how-to/multi-region-pricing"
+ "user/how-to/multi-region-pricing",
+ "user/how-to/wholesale-pricing",
+ "user/how-to/volume-pricing",
]
},
{
@@ -646,15 +648,14 @@
"user/settings/users",
"user/settings/emails",
"user/settings/policies",
- "user/settings/checkout",
"user/settings/domains",
- "user/settings/locations",
- "user/settings/metafields",
"user/settings/payments",
"user/settings/markets",
"user/settings/zones",
"user/settings/shipping-methods",
- "user/settings/tax"
+ "user/settings/tax",
+ "user/settings/locations",
+ "user/settings/metafields"
]
},
{
diff --git a/docs/images/user/how-to/volume-pricing/1-new-price-list-form.png b/docs/images/user/how-to/volume-pricing/1-new-price-list-form.png
new file mode 100644
index 0000000000..9ac749c4f8
Binary files /dev/null and b/docs/images/user/how-to/volume-pricing/1-new-price-list-form.png differ
diff --git a/docs/images/user/how-to/volume-pricing/2-volume-rule.png b/docs/images/user/how-to/volume-pricing/2-volume-rule.png
new file mode 100644
index 0000000000..1a7908fa5c
Binary files /dev/null and b/docs/images/user/how-to/volume-pricing/2-volume-rule.png differ
diff --git a/docs/images/user/how-to/volume-pricing/3-edit-prices.png b/docs/images/user/how-to/volume-pricing/3-edit-prices.png
new file mode 100644
index 0000000000..b52f4e6843
Binary files /dev/null and b/docs/images/user/how-to/volume-pricing/3-edit-prices.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/1-customer-groups.png b/docs/images/user/how-to/wholesale-pricing/1-customer-groups.png
new file mode 100644
index 0000000000..390947afd1
Binary files /dev/null and b/docs/images/user/how-to/wholesale-pricing/1-customer-groups.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/2-add-customers.png b/docs/images/user/how-to/wholesale-pricing/2-add-customers.png
new file mode 100644
index 0000000000..add773def5
Binary files /dev/null and b/docs/images/user/how-to/wholesale-pricing/2-add-customers.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/3-group-overview.png b/docs/images/user/how-to/wholesale-pricing/3-group-overview.png
new file mode 100644
index 0000000000..994f13c5b6
Binary files /dev/null and b/docs/images/user/how-to/wholesale-pricing/3-group-overview.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/4-new-price-list-form.png b/docs/images/user/how-to/wholesale-pricing/4-new-price-list-form.png
new file mode 100644
index 0000000000..1554b82e62
Binary files /dev/null and b/docs/images/user/how-to/wholesale-pricing/4-new-price-list-form.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/5-customer-group-rule.png b/docs/images/user/how-to/wholesale-pricing/5-customer-group-rule.png
new file mode 100644
index 0000000000..c404afaa4e
Binary files /dev/null and b/docs/images/user/how-to/wholesale-pricing/5-customer-group-rule.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/6-edit-prices.png b/docs/images/user/how-to/wholesale-pricing/6-edit-prices.png
new file mode 100644
index 0000000000..b409a0fe9a
Binary files /dev/null and b/docs/images/user/how-to/wholesale-pricing/6-edit-prices.png differ
diff --git a/docs/images/user/how-to/wholesale-pricing/placeholder b/docs/images/user/how-to/wholesale-pricing/placeholder
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/docs/images/user/how-to/wholesale-pricing/placeholder
@@ -0,0 +1 @@
+
diff --git a/docs/user/how-to/volume-pricing.mdx b/docs/user/how-to/volume-pricing.mdx
new file mode 100644
index 0000000000..6c06d4a5b2
--- /dev/null
+++ b/docs/user/how-to/volume-pricing.mdx
@@ -0,0 +1,92 @@
+---
+title: "Set Up Volume Pricing"
+description: "Learn how to offer tiered discounts based on order quantity using Price Lists in Spree Commerce."
+---
+
+Volume pricing lets you automatically offer lower prices when customers order larger quantities. A common use case is rewarding bulk buyers — for example, offering one price for orders of 21–50 units and a deeper discount for orders of 51–100 units.
+
+In Spree, you set this up using Price Lists with a Volume rule. Each pricing tier gets its own price list, and Spree applies the correct price automatically based on the quantity in the customer's order.
+
+In this guide, we'll set up two tiers: a mid-volume tier (21–50 units) and a high-volume tier (51–100 units).
+
+<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>
+
+## Prerequisites
+
+Before you start, you should have your products uploaded and set up with base prices. Volume pricing overrides those base prices when the quantity conditions are met — products without a base price will not be affected.
+
+Familiarity with how Price Lists work is helpful. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for a full reference.
+
+## 1. Create the First Volume Price List (21–50 Units)
+
+To create price list, navigate to **Products → Price Lists** in the admin dashboard and click **New Price List**.
+
+![The New Price List form in Spree Commerce](/docs/images/user/how-to/volume-pricing/1-new-price-list-form.png)
+
+Fill in the details for the first tier:
+
+- **Name** — e.g., `Volume Pricing (21–50 Units)`
+- **Description** — optional (e.g., `Mid-volume discount — applies when ordering between 21 and 50 units`)
+- **Start Date / End Date** — leave blank if this pricing should apply indefinitely
+
+Click **Create** to open the price list editor.
+
+### Add a Volume Rule
+
+In the price list editor, click **Add Rule** and select **Volume** from the rule type dropdown.
+
+![The price list editor showing a Volume rule with min and max quantity fields](/docs/images/user/how-to/volume-pricing/2-volume-rule.png)
+
+Set the quantity range for this tier:
+
+- **Min Quantity** — `21`
+- **Max Quantity** — `50`
+
+This ensures the price list only activates when a customer's order quantity falls within that range.
+
+### Add Products and Set Prices
+
+Click **Add Products** to open the product selector. Search for and select the products you want to include in this tier, then click **Add Selected**.
+
+Once the products appear in the list, click **Edit Prices** to open the price editor. Enter the discounted price for each product in the **Price** column.
+
+![The price editor showing discounted prices entered for the 21–50 unit tier](/docs/images/user/how-to/volume-pricing/3-edit-prices.png)
+
+Click **Save** to apply the prices, then click **Activate** (or **Schedule** if it has a future start date) to make the price list live.
+
+## 2. Create the Second Volume Price List (51–100 Units)
+
+Repeat the same process for the higher-volume tier. Click **New Price List** and fill in the details:
+
+- **Name** — e.g., `Volume Pricing (51–100 Units)`
+- **Description** — optional (e.g., `High-volume discount — applies when ordering between 51 and 100 units`)
+
+In the price list editor, add a **Volume** rule and set:
+
+- **Min Quantity** — `51`
+- **Max Quantity** — `100`
+
+Add the same products and enter the deeper discounted prices for this tier, then click **Save** and **Activate**.
+
+<Note>If you want pricing to apply for orders above 100 units with no upper limit, leave the **Max Quantity** field blank on that price list.</Note>
+
+## 3. Verify on the Storefront
+
+To confirm your volume tiers are working correctly, test by adding products to the cart in quantities that fall within each tier.
+
+1. Visit your storefront and add a product to the cart.
+2. Set the quantity to a value within the first tier (e.g., `25`) and confirm the mid-volume price is applied at checkout.
+3. Update the quantity to a value within the second tier (e.g., `60`) and confirm the deeper discount is applied.
+4. Set the quantity below the first tier threshold (e.g., `5`) and confirm the standard base price is shown.
+
+If the expected price is not being applied, check that:
+
+- The product has been added to the correct price list
+- The price list is set to **Active**
+- The Volume rule min and max quantities are correctly set and do not overlap between tiers
+
+## Next Steps
+
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, product selection, and price editing
+- [<u>Set Up Wholesale Pricing by Customer Group</u>](https://spreecommerce.org/docs/user/how-to/wholesale-pricing) — offer tiered pricing to specific customer segments
+- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — combine regional and volume rules for market-specific discounts
diff --git a/docs/user/how-to/wholesale-pricing.mdx b/docs/user/how-to/wholesale-pricing.mdx
new file mode 100644
index 0000000000..b9a3c070d6
--- /dev/null
+++ b/docs/user/how-to/wholesale-pricing.mdx
@@ -0,0 +1,95 @@
+---
+title: "Set Up Wholesale Pricing"
+description: "Learn how to offer wholesale pricing to specific customer groups using Price Lists in Spree Commerce."
+---
+
+Wholesale pricing lets you show different prices to different types of buyers — for example, trade customers or registered wholesalers see their negotiated prices, while regular customers continue to see standard retail prices. Because pricing is tied to the customer's account, there's no need for separate storefronts or manual price management.
+
+In Spree, you do this by creating a Customer Group for your wholesale buyers, then creating a Price List with a Customer Group rule that targets it. You can create as many price lists as you need — one per wholesaler or tier — each with its own pricing and conditions.
+
+<Note>This approach also enables a combined B2C and B2B setup on a single storefront: retail customers see base prices by default, while logged-in wholesale customers automatically see their contracted pricing. No separate store or login portal required.</Note>
+
+## Prerequisites
+
+Before you start, you should have your products set up with base prices. Wholesale pricing overrides those base prices for customers in the relevant group — all other customers continue to see the standard price.
+
+Familiarity with how Price Lists work is helpful. See [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) for a full reference.
+
+## 1. Create a Customer Group
+
+First, you'll need a Customer Group to represent your wholesale buyers. If you already have a suitable group set up, you can skip to [Step 2](#2-create-a-wholesale-price-list).
+
+Navigate to **Customers → Customer Groups** in the admin dashboard and click **New Customer Group**.
+
+![The Customer Groups overview page in Spree Commerce](/docs/images/user/how-to/wholesale-pricing/1-customer-groups.png)
+
+Fill in the details:
+
+- **Name** — e.g., `Wholesale Buyers` or a specific account name if this group is for a single wholesaler
+- **Description** — optional, but useful for other admins (e.g., `Registered trade accounts with negotiated wholesale pricing`)
+
+Click **Create** to save the group.
+
+## 2. Add Customers to the Group
+
+Once the group is created, you'll be taken to its detail view. Click **Add Customers** to open the customer selector panel.
+
+![The customer selector panel open in Spree Commerce](/docs/images/user/how-to/wholesale-pricing/2-add-customers.png)
+
+Search for the customers you want to include, check the boxes next to their names, and click **Add Selected**. The customers will now appear in the group.
+
+![Users added to a customer group in Spree Commerce](/docs/images/user/how-to/wholesale-pricing/3-group-overview.png)
+
+Repeat this process whenever you onboard a new wholesale account — simply add them to the relevant group and their pricing will apply automatically on their next login.
+
+## 3. Create a Wholesale Price List
+
+With your customer group in place, navigate to **Products → Price Lists** and click **New Price List**.
+
+![The New Price List form in Spree Commerce](/docs/images/user/how-to/wholesale-pricing/4-new-price-list-form.png)
+
+Fill in the details:
+
+- **Name** — e.g., `Wholesale Buyers Pricing`
+- **Description** — optional (e.g., `Standard wholesale pricing for registered trade accounts`)
+- **Start Date / End Date** — leave blank if this pricing should apply indefinitely
+
+Click **Create** to open the price list editor.
+
+### Add a Customer Group Rule
+
+In the price list editor, click **Add Rule** and select **Customer Group** from the rule type dropdown. Select **Wholesale Buyers** from the options.
+
+![The price list editor showing a Customer Group rule targeting Wholesale Buyers](/docs/images/user/how-to/wholesale-pricing/5-customer-group-rule.png)
+
+This ensures the price list only applies to logged-in customers who are members of that group.
+
+### Add Products and Set Prices
+
+Click **Add Products** to open the product selector. Search for and select the products you want to include in this price list, then click **Add Selected**.
+
+Once the products appear in the list, click **Edit Prices** to open the price editor. Enter the wholesale price for each product in the **Price** column.
+
+![The price editor showing wholesale prices entered for the Wholesale Buyers price list](/docs/images/user/how-to/wholesale-pricing/6-edit-prices.png)
+
+Click **Save** to apply the prices, then click **Activate** (or **Schedule** if it has a future start date) to make the price list live.
+
+<Note>If you work with multiple wholesalers on different negotiated terms, create a separate Customer Group and Price List for each. For example, a `Distributor A` group and `Distributor A Pricing` list, and a `Distributor B` group with its own list. Each wholesaler's customers will only ever see their own contracted prices.</Note>
+
+## 4. 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 and browse to a product you included in the price list. The wholesale price should be displayed instead of the standard retail price.
+
+If the expected price is not showing, check that:
+
+- The customer's account has been added to the correct Customer Group
+- The product has been added to the price list
+- The price list is set to **Active**
+- The Customer Group rule is correctly configured
+
+## Next Steps
+
+- [<u>Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups) — full reference for creating and managing customer groups
+- [<u>Price Lists</u>](https://spreecommerce.org/docs/user/manage-products/price-lists) — full reference for rules, product selection, and price editing
+- [<u>Set Up Volume Pricing</u>](https://spreecommerce.org/docs/user/how-to/volume-pricing) — add quantity-based tiers on top of your wholesale pricing
+- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — apply regional price variations within a customer group
diff --git a/docs/user/settings/domains.mdx b/docs/user/settings/domains.mdx
index 3a6e402f76..7ec36c8cde 100644
--- a/docs/user/settings/domains.mdx
+++ b/docs/user/settings/domains.mdx
@@ -5,6 +5,8 @@ description: "Learn how to connect custom domains to your Spree store."
Connecting a custom domain ensures your store is accessible via a branded, customer-friendly URL, rather than a technical or temporary address. It builds trust with users, strengthens brand identity, and improves discoverability through SEO.
+<Note>Custom domain support requires the `spree-multi-store` package. See the [<u>Multi-Store Quickstart</u>](https://spreecommerce.org/docs/developer/multi-store/quickstart) for setup instructions.</Note>
+
### Add a Custom Domain
Adding custom domains in Spree is made simple with a convenient semi-automated process.
@@ -24,4 +26,4 @@ Once verified, the domain is automatically connected and enabled for use with yo
The system handles most of the DNS configuration behind the scenes. However, if your domain is managed through a provider that isn’t supported for automated setup, you may be required to complete some manual DNS changes (instructions will be provided as needed).
-<Note>Changes to DNS records may take some time to propagate, depending on your domain provider.</Note>
\ No newline at end of file
+<Note>Changes to DNS records may take some time to propagate, depending on your domain provider.</Note>
diff --git a/docs/user/settings/locations.mdx b/docs/user/settings/locations.mdx
index 5d850f848b..f14e0b9bb5 100644
--- a/docs/user/settings/locations.mdx
+++ b/docs/user/settings/locations.mdx
@@ -1,5 +1,5 @@
---
-title: "Locations"
+title: "Stock Locations"
description: "Learn how to create and manage stock locations in Spree Commerce."
---
diff --git a/docs/user/settings/metafields.mdx b/docs/user/settings/metafields.mdx
index aa63b7f40f..3a0616d567 100644
--- a/docs/user/settings/metafields.mdx
+++ b/docs/user/settings/metafields.mdx
@@ -1,5 +1,5 @@
---
-title: "Metafields"
+title: "Metafield Definitions"
description: "Learn how to define and use metafields in Spree Commerce"
---