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
[Skip CI] Added docs for promotion actions and rules (#13478)
jaburghes47e9833ba3f7
diff --git a/docs/docs.json b/docs/docs.jsonindex 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.mdxindex 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 Usediff --git a/docs/user/promotions/promotion-actions.mdx b/docs/user/promotions/promotion-actions.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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 |