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 'Price Lists' and 'Create a Promotion' user docs (#13457)

jaburghesa34e01dd8705
diff --git a/docs/docs.json b/docs/docs.json
index 2c7e9dcea8..2747119fce 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -984,6 +984,7 @@
"pages": [
"user/manage-products/search-products",
"user/manage-products/bulk-product-operations",
+ "user/manage-products/price-lists",
"user/manage-products/export-products",
"user/manage-products/import-products",
"user/manage-products/product-import-file-template",
@@ -1028,6 +1029,12 @@
"user/customers/exporting-customers"
]
},
+ {
+ "group": "Promotions",
+ "pages": [
+ "user/promotions/create-a-promotion"
+ ]
+ },
{
"group": "Vendors",
"pages": [
diff --git a/docs/images/user/products/price-lists/1-price-lists-tab.png b/docs/images/user/products/price-lists/1-price-lists-tab.png
new file mode 100644
index 0000000000..75779ff0fc
Binary files /dev/null and b/docs/images/user/products/price-lists/1-price-lists-tab.png differ
diff --git a/docs/images/user/products/price-lists/2-price-list-form.png b/docs/images/user/products/price-lists/2-price-list-form.png
new file mode 100644
index 0000000000..201ce377bc
Binary files /dev/null and b/docs/images/user/products/price-lists/2-price-list-form.png differ
diff --git a/docs/images/user/products/price-lists/3-edit-form.png b/docs/images/user/products/price-lists/3-edit-form.png
new file mode 100644
index 0000000000..c9cc0fb320
Binary files /dev/null and b/docs/images/user/products/price-lists/3-edit-form.png differ
diff --git a/docs/images/user/products/price-lists/4-price-list-rules.png b/docs/images/user/products/price-lists/4-price-list-rules.png
new file mode 100644
index 0000000000..b02c5dc9be
Binary files /dev/null and b/docs/images/user/products/price-lists/4-price-list-rules.png differ
diff --git a/docs/images/user/products/price-lists/5-add-products.png b/docs/images/user/products/price-lists/5-add-products.png
new file mode 100644
index 0000000000..de24a84aab
Binary files /dev/null and b/docs/images/user/products/price-lists/5-add-products.png differ
diff --git a/docs/images/user/products/price-lists/6-select-products.png b/docs/images/user/products/price-lists/6-select-products.png
new file mode 100644
index 0000000000..71f0560b6f
Binary files /dev/null and b/docs/images/user/products/price-lists/6-select-products.png differ
diff --git a/docs/images/user/products/price-lists/7-edit-prices.png b/docs/images/user/products/price-lists/7-edit-prices.png
new file mode 100644
index 0000000000..8c3d313241
Binary files /dev/null and b/docs/images/user/products/price-lists/7-edit-prices.png differ
diff --git a/docs/images/user/products/price-lists/8-update-values.png b/docs/images/user/products/price-lists/8-update-values.png
new file mode 100644
index 0000000000..46300c3693
Binary files /dev/null and b/docs/images/user/products/price-lists/8-update-values.png differ
diff --git a/docs/images/user/products/price-lists/9-active-price-list.png b/docs/images/user/products/price-lists/9-active-price-list.png
new file mode 100644
index 0000000000..72ef2f99b3
Binary files /dev/null and b/docs/images/user/products/price-lists/9-active-price-list.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/1-promotions-tab.png b/docs/images/user/promotions/create-a-promotion/1-promotions-tab.png
new file mode 100644
index 0000000000..75f7fc7b06
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/1-promotions-tab.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/2-new-promotion.png b/docs/images/user/promotions/create-a-promotion/2-new-promotion.png
new file mode 100644
index 0000000000..0929c1f726
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/2-new-promotion.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/3-promotion-kind.png b/docs/images/user/promotions/create-a-promotion/3-promotion-kind.png
new file mode 100644
index 0000000000..f632978e3e
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/3-promotion-kind.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/4-promotion-settings.png b/docs/images/user/promotions/create-a-promotion/4-promotion-settings.png
new file mode 100644
index 0000000000..cffef114d5
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/4-promotion-settings.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/5-promo-edit-form.png b/docs/images/user/promotions/create-a-promotion/5-promo-edit-form.png
new file mode 100644
index 0000000000..f6c8d62b77
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/5-promo-edit-form.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/6-promo-rules.png b/docs/images/user/promotions/create-a-promotion/6-promo-rules.png
new file mode 100644
index 0000000000..e39c84a75d
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/6-promo-rules.png differ
diff --git a/docs/images/user/promotions/create-a-promotion/7-promo-actions.png b/docs/images/user/promotions/create-a-promotion/7-promo-actions.png
new file mode 100644
index 0000000000..15aed8f7af
Binary files /dev/null and b/docs/images/user/promotions/create-a-promotion/7-promo-actions.png differ
diff --git a/docs/user/manage-products/price-lists.mdx b/docs/user/manage-products/price-lists.mdx
new file mode 100644
index 0000000000..fcf73bfd18
--- /dev/null
+++ b/docs/user/manage-products/price-lists.mdx
@@ -0,0 +1,86 @@
+---
+title: "Price Lists"
+description: "Learn how to set up volume pricing, user-specific pricing, and more in Spree Commerce."
+---
+
+Price lists are a powerful tool for managing customer-specific pricing strategies - essential for industries like B2B, wholesale, and marketplaces. They let you offer different prices to different customer segments based on conditions like location, quantity, or account status, without needing to duplicate product records or use heavy customizations.
+
+With Spree’s native support for price lists, you can create and manage custom pricing logic directly in the admin dashboard - no development required.
+
+## Create a Price List
+
+To get started, navigate to **Products → Price Lists** in the admin dashboard. 
+
+![The price list tab in Spree Commerce](/docs/images/user/products/price-lists/1-price-lists-tab.png)
+
+Here, you’ll see an overview of all active and inactive price lists. Click **New Price List** in the top right corner to open the price list creation form.
+
+![Creating a new price list in Spree Commerce](/docs/images/user/products/price-lists/2-price-list-form.png)
+
+Fill in the following fields:
+
+- **Name** - Internal name for the price list (displayed in the admin).
+- **Description (optional)** - Notes or context for other admins.
+- **Start Date** and **End Date** - Defines when the price list should be active.
+ - If not set, the price list will take effect immediately and it will never expire
+
+Once you’ve completed the above, click **Create** to proceed.
+
+## Configure a Price List
+
+![The price list editor in Spree Commerce](/docs/images/user/products/price-lists/3-edit-form.png)
+
+Once created, you’ll be redirected to the price list edit form, where you can define rules for when the price list should apply, add products to be included in the price list, and set the modified prices of those products.
+
+### Add Rules
+
+![Adding rules to a price list in Spree Commerce](/docs/images/user/products/price-lists/4-price-list-rules.png)
+
+You can add multiple rules with Match Any or Match All logic.
+
+Available Rule Types:
+
+- **User** - Apply pricing only for specific users.
+- **Customer Group** - Apply pricing to a specific customer group.
+- **Volume** - Apply pricing when order quantity falls within a min–max range.
+- **Zone** - Apply pricing to customers in a specific tax/shipping zone.
+
+To add a rule, simply click **Add Rule**, select a rule type, and configure its criteria.
+
+### Add Products
+
+![Adding product to a price list in Spree Commerce](/docs/images/user/products/price-lists/5-add-products.png)
+
+Next, you’ll need to add some products to the price list. To do so, click **Add Products** in Products subsection to open the product selector side panel.
+
+![Selecting products to add to a price list in Spree Commerce](/docs/images/user/products/price-lists/6-select-products.png)
+
+Search for products by name or SKU, select one or more products and click **Add Selected** to add them to the price list.
+
+The selected products will now appear in the product list.
+
+### Setting Prices
+
+To define custom prices for the list, click **Edit Prices** in the top right of the product list to open the price edit form.
+
+![How to edit prices on price list in Spree Commerce](/docs/images/user/products/price-lists/7-edit-prices.png)
+
+Select which currency you'd like to update prices for, and update the values in the **Price** column and optionally in the **Compare At** column.
+
+<Note>You can highlight multiple fields and copy + paste like you would in a spreadsheet.</Note>
+
+![Updating price lists values in the Spree Commerce dashboard](/docs/images/user/products/price-lists/8-update-values.png)
+
+Once you’ve finished entering the custom prices, click **Save** to apply your changes. 
+
+## Activating the Price List
+
+Once everything is configured, go back to the price list editor, and click **Activate** in the top right corner.
+
+![Activating a price list in Spree Commerce](/docs/images/user/products/price-lists/9-active-price-list.png)
+
+The price list will now take effect immediately for any user or order that matches the configured rules.
+
+You can deactivate the price list at any time by clicking the **Deactivate** button.
+
+<Note>If you set a start date for the price list, the **Activate/Deactivate** button will instead say **Schedule/Unschedule**.</Note>
diff --git a/docs/user/promotions/create-a-promotion.mdx b/docs/user/promotions/create-a-promotion.mdx
new file mode 100644
index 0000000000..dae8ea6cbf
--- /dev/null
+++ b/docs/user/promotions/create-a-promotion.mdx
@@ -0,0 +1,145 @@
+---
+title: "Create a Promotion"
+description: "Learn to how to create and configure promotions in Spree Commerce."
+---
+
+Promotions are a powerful way to drive conversions, reward loyal customers, and support marketing campaigns. Whether you’re offering discounts, free shipping, or bonus products, Spree’s promotion engine gives you fine-grained control over when a promotion applies and what it does.
+
+This guide covers how to create and configure a promotion in Spree. Detailed explanations of individual rules and actions are covered in separate articles.
+
+## Create a New Promotion
+
+To create a promotion, navigate to the **Promotions** tab in the admin dashboard.
+
+![The promotions tab in Spree Commerce](/docs/images/user/promotions/create-a-promotion/1-promotions-tab.png)
+
+Click **New Promotion** in the top-right corner, to open the Promotion creation form.
+
+![Creating a new promotion in Spree Commerce](/docs/images/user/promotions/create-a-promotion/2-new-promotion.png)
+
+Here you can do the following:
+
+### Choose a Promotion Type
+
+![Choosing the type of promotion in Spree Commerce](/docs/images/user/promotions/create-a-promotion/3-promotion-kind.png)
+
+When creating a promotion, you’ll first select how it’s applied:
+
+- **Coupon Code** - The promotion is applied only when a valid code is entered at checkout. You can choose between:
+ - **Single Code** - one shared code (e.g. SUMMER10)
+ - **Generated Codes** - automatically generate unique codes
+ - Optional prefix (e.g. VIP-)
+ - Set how many codes should be generated
+ - Unique codes can be downloaded for easier distribution
+- **Automatic** - The promotion is applied automatically at checkout once its conditions are met . No coupon code required.
+ - This is ideal for sitewide sales, free shipping offers, or first-time customer discounts.
+
+### Configure Promotion Settings
+
+![Configure promotion settings in Spree Commerce](/docs/images/user/promotions/create-a-promotion/4-promotion-settings.png)
+
+Next, configure the promotion’s availability and limits:
+
+- **Usage Limit** - Maximum number of times the promotion can be used (optional).
+- **Starts At** - Date and time when the promotion becomes active.
+- **Expires At** - Date and time when the promotion is no longer valid.
+
+Once these fields are set, click **Create**, the form will update, and you can now configure the rules and actions for the promotion.
+
+## Configure Rules & Actions
+
+![The promotion edit form in Spree Commerce](/docs/images/user/promotions/create-a-promotion/5-promo-edit-form.png)
+
+After creating the promotion, you’ll be redirected to the main configuration screen. This is where the actual logic of the promotion is defined.
+
+You’ll see two main sections:
+
+- **Rules** - determine when the promotion applies
+- **Actions** - determine what happens when it applies
+
+<Warning>When adding a rule or action, changes are saved immediately.</Warning>
+
+There are also two side panels that let you update:
+
+- Promotion details (name, code)
+- Promotion settings (usage limits, start/end dates)
+
+### Promotion Rules (Conditions)
+
+![Setting promotion rules in Spree Commerce](/docs/images/user/promotions/create-a-promotion/6-promo-rules.png)
+
+Rules define eligibility. You can combine multiple rules using:
+
+- **Match any** - at least one rule must be satisfied
+- **Match all** - all rules must be satisfied
+
+Available rule types include:
+
+- **Currency** - Order must be in a specific currency
+- **Country** - Shipping address must be in a specific country
+- **Item Total** - Order total meets defined thresholds
+- **Product(s)** - Order contains specific products
+- **User** - Available only to specific customers
+- **First Order** - Customer’s first purchase only
+- **User Logged In** - Requires the customer to be logged in
+- **One Use Per User** - Limits redemption to once per customer
+- **Taxon(s)** - Order contains products from selected taxons
+- **Option Value(s)** - Order contains products with specific option values
+
+Rule behavior and configuration details are covered in Promotion Rules.
+
+### Promotion Actions (Effects)
+
+![Setting promotion actions in Spree Commerce](/docs/images/user/promotions/create-a-promotion/7-promo-actions.png)
+
+Actions define what the promotion does once its rules are satisfied.
+
+Available actions include:
+
+- **Create whole-order adjustment** - Applies a discount to the entire order.
+- **Create per-line-item adjustment** - Applies discounts to individual line items.
+- **Create line items** - Automatically adds products (e.g. gifts) to the cart.
+- **Free shipping** - Makes all shipments for the order free.
+
+Each action supports one or more calculators (e.g. flat rate, percentage, tiered discounts). These are covered in detail in Promotion Actions.
+
+## Promotion Ready to Use
+
+Once you’ve added the promotion’s rules and actions, it’s ready to be used by customers.
+
+- **Automatic promotions** will apply at checkout as soon as the conditions are met.
+- **Coupon code promotions** can be redeemed when customers enter the code during checkout.
+
+How you market, distribute, or communicate the promotion (e.g., email campaigns, banners, social media, influencer codes) is entirely up to you and your team.
+
+## Common Promotion Examples
+
+**10% Off with a Coupon Code**
+
+- Type: Coupon Code (single code)
+- Rule: None (or minimum order total)
+- Action: Whole-order adjustment → 10% discount
+
+**Free Shipping Over \$50**
+
+- Type: Automatic
+- Rule: Item total ≥ \$50
+- Action: Free shipping
+
+**First-Time Customer Discount**
+
+- Type: Automatic
+- Rules: First order, User logged in
+- Action: Whole-order adjustment → flat or percentage discount
+
+**Buy from a Category, Get a Discount**
+
+- Type: Automatic
+- Rule: Taxon(s)
+- Action: Per-line-item adjustment
+
+**Advanced Example: VIP Coupon for EU Customers**
+
+- Type: Coupon Code (generated unique codes with prefix)
+- Rules: User, One use per user, Currency
+- Action: Whole-order adjustment with tiered percentage calculator