Documentation Index
Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Promotions within Spree are used to provide discounts to orders, offer free shipping, or add items at no extra cost (e.g., free gifts). The promotion system is highly flexible, allowing you to create complex promotional campaigns based on various conditions.
Key relationships:
- Promotion defines the campaign with rules and actions
- Promotion Rules determine eligibility conditions (FirstOrder, ItemTotal, Taxon, etc.)
- Promotion Actions define what happens when applied (discount, free shipping, free items)
- Coupon Codes track usage for code-based promotions
- Adjustments are created on orders/line items to apply discounts
Promotions can be activated in two ways:
- Automatic promotions - Applied automatically when eligibility rules are met (e.g., free shipping on orders over $50)
- Coupon code promotions - Applied when a customer enters a valid code during checkout
Promotions consist of two main components:
- Rules - Conditions that must be met for the promotion to apply
- Actions - What happens when the promotion is applied (discount, free shipping, etc.)
| Attribute | Description | Example |
|---|
name | The name of the promotion | Summer Sale |
description | Brief description (max 255 chars) | 20% off all summer items |
kind | Type: coupon_code or automatic | automatic |
starts_at | When the promotion becomes active | 2025-06-01 00:00:00 |
expires_at | When the promotion expires | 2025-09-01 23:59:59 |
usage_limit | Max times the promotion can be used | 500 |
match_policy | How rules are evaluated: all or any | all |
advertise | Whether to display on storefront | true |
path | SEO-friendly URL path | summer-sale |
| Attribute | Description | Example |
|---|
multi_codes | Enable bulk code generation | true |
number_of_codes | How many codes to generate | 1000 |
code_prefix | Prefix for generated codes | SUMMER |
{prefix}{random}, e.g., SUMMER22A0F62A230BD919.
Rules
Rules determine when a promotion is eligible. You can combine multiple rules and configure whether all rules must match or any rule is sufficient (via match_policy).
FirstOrder
Applies only to a customer’s first order. Checks both user account and email address to prevent abuse.
Use case: Welcome discount for new customers.
ItemTotal
Requires the order subtotal to meet minimum and/or maximum thresholds.
Configuration:
preferred_amount_min - Minimum order amount (default: 100.00)preferred_operator_min - Comparison operator: gt (greater than) or gte (greater than or equal)preferred_amount_max - Maximum order amount (optional)preferred_operator_max - Comparison operator: lt (less than) or lte (less than or equal)
Use case: “Free shipping on orders over 50","10100-$500”.
Product
Requires specific products to be in the order.
Configuration:
preferred_match_policy:
any - At least one of the specified productsall - All specified products must be presentnone - None of the specified products (exclusion)
Use case: “Buy Product A and get 20% off”, “Discount excludes sale items”.
Taxon
Requires products from specific categories (taxons) to be in the order.
Configuration:
preferred_match_policy: any or all
The rule automatically includes products in child taxons when a parent taxon is selected.
Use case: “20% off Electronics”, “Buy from Shoes category get 10% off”.
User
Limits the promotion to specific customer accounts.
Use case: Employee discounts, VIP customer promotions.
UserLoggedIn
Requires the customer to be logged in with an account.
Use case: Member-only discounts.
OneUsePerUser
Ensures each customer can only use the promotion once.
Use case: One-time welcome offers, limited redemption campaigns.
Country
Limits the promotion to orders shipping to a specific country.
Configuration:
preferred_country_id or preferred_country_iso (ISO 2-letter code)
Use case: Regional promotions, country-specific campaigns.
Currency
Limits the promotion to orders in a specific currency.
Configuration:
preferred_currency - Currency code (e.g., “USD”, “EUR”)
Use case: Currency-specific pricing strategies.
OptionValue
Requires products with specific option values (e.g., size, color) to be in the order.
Configuration:
preferred_eligible_values - Array of eligible variant IDs
Use case: “10% off all red items”, “Discount on size XL”.
CustomerGroup
Limits the promotion to customers belonging to specific customer groups.
Configuration:
preferred_customer_group_ids - Array of customer group IDs
Customer groups are managed in Admin > Customers > Customer Groups and allow you to segment customers for targeted promotions.
Use case: VIP programs, loyalty tiers, wholesale pricing, B2B customer segments.
Actions
Actions define what happens when a promotion is applied.
CreateAdjustment
Creates a discount on the entire order total.
Default calculator: FlatPercentItemTotal (percentage off order)
Available calculators:
FlatPercentItemTotal - Percentage off the order totalFlatRate - Fixed amount offFlexiRate - First item at one rate, additional items at anotherTieredFlatRate - Different rates based on order total tiersTieredPercent - Different percentages based on order total tiers
Use case: “10% off your order”, “20offordersover100”.
CreateItemAdjustments
Creates discounts on individual line items. Only applies to items that match the promotion rules (e.g., items in a specific category).
Default calculator: PercentOnLineItem (percentage off each item)
The action respects rule actionability - if a Taxon rule specifies “Electronics”, only electronics items receive the discount.
Use case: “15% off shoes”, “Buy 2+ shirts get 10% off each”.
FreeShipping
Makes all shipments free by creating negative adjustments equal to shipping costs.
Use case: “Free shipping on orders over $75”, “Free shipping with code FREESHIP”.
CreateLineItems
Automatically adds specified products to the cart when the promotion is eligible.
Configuration:
- Map of variant IDs to quantities to add
The action checks stock availability before adding items. Items are not automatically removed if eligibility is lost - customers must remove them manually.
Use case: “Free gift with purchase”, “Buy 2 get 1 free”, “Spend $100 get free sample”.
Coupon Codes
Coupon codes track promotion usage and can be single-use or multi-use.
Set the code attribute directly on the promotion. The usage_limit controls how many times it can be redeemed.
For bulk-generated codes, each code tracks its usage state:
| Attribute | Description | Example |
|---|
code | The unique code | SUMMER22A0F62A230BD919 |
state | Usage state | unused, used |
Applying Coupon Codes via Store API
Customers apply coupon codes during checkout via the Store API:
// Apply a discount code to the cart
const cart = await client.carts.discountCodes.apply('cart_abc123', 'SUMMER20', {
spreeToken: '<token>',
})
// Remove a discount code from the cart
await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {
spreeToken: '<token>',
})
- Order Update — When an order is updated, the system checks all eligible promotions
- Eligibility Check — For each promotion:
- Check if within
starts_at and expires_at range
- Check if under
usage_limit
- Evaluate all rules based on
match_policy (all or any)
- Action Execution — If eligible, each action is applied
- Tracking — Applied promotions are recorded on the order
- Re-evaluation — Eligibility is re-checked on every order update; adjustments from ineligible promotions are removed
