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.

[Skip CI] Added docs for promotion actions and rules (#13478)

jaburghes47e9833ba3f7
diff --git a/docs/docs.json b/docs/docs.json
index 836a152aba..c78a3719e2 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1033,7 +1033,9 @@
{
"group": "Promotions",
"pages": [
- "user/promotions/create-a-promotion"
+ "user/promotions/create-a-promotion",
+ "user/promotions/promotion-rules",
+ "user/promotions/promotion-actions"
]
},
{
diff --git a/docs/user/promotions/create-a-promotion.mdx b/docs/user/promotions/create-a-promotion.mdx
index dae8ea6cbf..a7b30d4e3b 100644
--- a/docs/user/promotions/create-a-promotion.mdx
+++ b/docs/user/promotions/create-a-promotion.mdx
@@ -86,7 +86,7 @@ Available rule types include:
- **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.
+Rule behavior and configuration details are covered in [<u>Promotion Rules</u>](https://spreecommerce.org/docs/user/promotions/promotion-rules).
### Promotion Actions (Effects)
@@ -101,7 +101,7 @@ Available actions include:
- **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.
+Each action supports one or more calculators (e.g. flat rate, percentage, tiered discounts). These are covered in detail in [<u>Promotion Actions</u>](https://spreecommerce.org/docs/user/promotions/promotion-actions).
## Promotion Ready to Use
diff --git a/docs/user/promotions/promotion-actions.mdx b/docs/user/promotions/promotion-actions.mdx
new file mode 100644
index 0000000000..c0eaeea566
--- /dev/null
+++ b/docs/user/promotions/promotion-actions.mdx
@@ -0,0 +1,90 @@
+---
+title: "Promotion Actions"
+description: "Learn how to use promotion actions in Spree Commerce."
+---
+
+Promotion actions define what happens when a promotion is applied. Once a promotion’s rules are met (if any), its actions are either triggered automatically at checkout or when applying the coupon code on checkout.
+
+Actions can apply discounts, add items to the cart, or make shipping free - and each action can be customized further using various calculators.
+
+## Available Promotion Actions
+
+Here are the actions you can apply to a promotion in Spree:
+
+### Create Whole-Order Adjustment
+
+Applies a discount to the entire order total.
+
+This is ideal for:
+
+- Sitewide sales (e.g., 10% off everything)
+- Cart value promotions (e.g., \$20 off orders over \$100)
+
+### Create Per-Line-Item Adjustment
+
+Applies a discount individually to eligible line items in the order.
+
+This is best used when:
+
+- You want to discount only certain products or product groups
+- You’re combining with Product, Taxon, or Option Value rules
+
+Each qualifying item will receive a proportional discount based on the calculator settings.
+
+### Create Line Items
+
+Automatically adds products to the customer’s cart when the promotion applies.
+
+Common uses:
+
+- “Buy X, get Y free” campaigns
+- Gift-with-purchase offers
+- Sample distribution
+
+You’ll be able to:
+
+- Select the variant(s) to add
+- Set the quantity
+- Combine with other actions to set price rules (e.g., set to free or discounted)
+
+### Free Shipping
+
+Makes all shipments in the order free.
+
+Best used when:
+
+- Offering free shipping above a certain threshold
+- Running promotional periods with free delivery
+
+This action zeroes out the shipping cost - no calculator needed.
+
+## Configuring Actions with Calculators
+
+Most actions (except Free Shipping) support the use of calculators to control how the discount is applied.
+
+The available calculators are as follows:
+
+- **Flat Rate** - Apply a fixed discount amount (e.g., \$10 off)
+- **Flat Percent** - Apply a percentage discount (e.g., 15% off)
+- **Flexible Rate** - Apply a base discount + per-item amount
+- **Tiered Flat Rate** - Different flat discounts based on order value or item count
+- **Tiered Percent** - Varying percentage discounts based on thresholds
+
+Example: A tiered flat rate could apply \$5 off orders over \$50, and \$10 off orders over \$100.
+
+You'll choose a calculator when you add the action. The fields shown will depend on the calculator type selected.
+
+## Notes on Behavior
+
+- You can add multiple actions to the same promotion (e.g., discount + free shipping).
+- Changes to actions are saved immediately after adding or updating them.
+- Actions apply only after all rules (if any) are satisfied.
+
+## Example Use Cases
+
+| **Goal** | **Action(s)** | **Calculator** |
+| :---------------------------------- | :---------------------------------------- | :------------------------------------------ |
+| \$10 off entire order | Whole-order adjustment | Flat Rate |
+| 20% off selected products | Per-line-item adjustment | Flat Percent |
+| Add a free tote bag on orders \$50+ | Create line items, Whole-order adjustment | Flat Rate (set to price of added line item) |
+| Free shipping on all orders | Free shipping | – |
diff --git a/docs/user/promotions/promotion-rules.mdx b/docs/user/promotions/promotion-rules.mdx
new file mode 100644
index 0000000000..65705b1de1
--- /dev/null
+++ b/docs/user/promotions/promotion-rules.mdx
@@ -0,0 +1,130 @@
+---
+title: "Promotion Rules"
+description: "Learn how to use promotion rules in Spree Commerce."
+---
+
+Promotion rules define the conditions that must be met for a promotion to be applied. Spree gives you full control over when a promotion should be eligible - whether it’s based on the order total, customer group, specific products, or a user’s login status.
+
+Each promotion can have multiple rules, and you can choose whether all rules must match (match all) or any rule must match (match any).
+
+## Rule Match Policies
+
+At the top of the Rules section in the promotion editor, you’ll see the Match Policy toggle:
+
+- **Match all** - All rules must be satisfied for the promotion to apply.
+- **Match any** - Only one rule needs to be satisfied.
+
+This gives you flexibility to fine-tune how strict or lenient the promotion conditions should be.
+
+## Available Promotion Rules
+
+Below is a list of all rule types currently supported in Spree, along with when and why you might use them.
+
+### Item Total
+
+Applies the promotion only if the order total meets a specific threshold.
+
+Use this when:
+
+- Offering discounts above a certain spend (e.g. \$50+ orders)
+- Creating tiered incentives for larger carts
+
+### Country
+
+Limits the promotion to customers whose shipping address is in a specific country.
+
+Useful for:
+
+- International promotions
+- Localized campaigns (e.g., “Free shipping in the US”)
+
+### Currency
+
+Applies the promotion only to orders in a specific currency.
+
+Use this if:
+
+- You're running different promotions in different markets
+- You want to avoid coupon misuse across regional stores
+
+### Product(s)
+
+Limits the promotion to orders that include one or more specific products (variants).
+
+Perfect for:
+
+- Targeted discounts on select SKUs
+- Bundling or cross-sell offers
+
+### Taxon(s)
+
+Applies when the order includes products belonging to specific taxons (categories, collections, etc.).
+
+Ideal for:
+
+- Category-wide promotions (e.g., “25% off all shoes”)
+- Seasonal or campaign-specific collections
+
+### Option Value(s)
+
+Triggers when products in the cart have a specific option value (e.g., color, size, material).
+
+Use cases:
+
+- Color-specific clearance sales
+- Size-limited inventory promos
+
+### User
+
+Applies only to specific customers.
+
+This is useful for:
+
+- VIP offers
+- Manually targeting customers (e.g. after support tickets, outreach)
+
+### First Order
+
+Applies only if the promotion is being used on a customer’s first-ever order.
+
+Great for:
+
+- Welcome offers
+- Signup conversion boosts
+
+### User Logged In
+
+Applies only when the customer is logged in.
+
+Use this to:
+
+- Encourage account creation
+- Hide promotions from guest checkout users
+
+### One Use Per User
+
+Restricts the promotion so that each user can only use it once.
+
+Helps prevent abuse and maintain exclusivity.
+
+### Customer Group
+
+Limits the promotion to customers belonging to a specific Customer Group.
+
+Perfect for:
+
+- Wholesale or B2B-only promotions
+- Segment-specific campaigns (e.g., “Early Access” or “Loyal Customers”)
+
+Customer Groups are created under [<u>Customers → Customer Groups</u>](https://spreecommerce.org/docs/user/customers/customer-groups).
+
+## Example Use Cases
+
+| **Goal** | **Rule(s) to Use** |
+| :------------------------------------ | :------------------------------ |
+| \$10 off first order only | First Order + User Logged In |
+| 20% off selected category | Taxon(s) |
+| Exclusive deal for logged-in VIPs | User Logged In + Customer Group |
+| Free shipping to U.S. only | Country (US) |
+| Discount on red-colored items | Option Value(s) → Color: Red |
+| Welcome promo limited to one-time use | First Order + One Use Per User |