actions
and rules
. When a promotion is activated, the actions for the promotion are performed, passing in the payload from the fire_event
call that triggered the activator becoming active. Rules are used to determine if a promotion meets certain criteria in order to be applicable.
Here is a table showcasing the attributes of the Spree::Promotion
model along with a description for each attribute and example values:
Attribute | Description | Example Value |
---|---|---|
name | The name of the promotion | Summer Sale |
description | A brief description of the promotion | Discounts for summer |
expires_at | The expiration date and time of the promotion | 2025-09-01 23:59:59 |
starts_at | The start date and time of the promotion | 2025-06-01 00:00:00 |
code | A code that users can enter to apply the promotion | SUMMER2023 |
usage_limit | The total number of times the promotion can be used | 500 |
match_policy | The policy for how promotion rules are matched | all |
path | The specific path that activates the promotion | /summer-sale |
per_code_usage_limit | The number of times a single code can be used | 1 |
Spree::PromotionHandler::Page
class is used, as in Spree::ContentController
from spree_rails_frontend gemCreating an Adjustment
When a CreateAdjustment
action is undertaken, an adjustment is automatically applied to the order, unless the promotion has already applied an adjustment to the order.
Once the adjustment has been applied to the order, its eligibility is re-checked every time the order is saved, by way of the Promotion#eligible?
method, which uses Promotion#eligible_rules
to determine if the promotion is still eligible based on its rules. For how this process works, please see the rules section below.
An adjustment to order from a promotion depends on the calculators. For more information about calculators, please see the Calculators guide.
Creating an Item Adjustment
When a CreateItemAdjustments
action is undertaken, an adjustment is automatically applied to each item within the order unless the action has already been performed on that line item.
The eligibility of the item for this promotion is re-checked whenever the item is updated. Its eligibility is based on the rules of the promotion.
An adjustment to order from a promotion depends on the calculators. For more information about calculators, please see the Calculators guide.
Free Shipping
When a FreeShipping
action is undertaken, all shipments within the order have their prices negated. Just like with prior actions, the eligibility of this promotion is checked again whenever a shipment changes.
Create Line Items
When a CreateLineItem
action is undertaken, a series of line items are automatically added to the order, which may alter the order’s price. The promotion with an action to add a line item can also have another action to add an adjustment to the order to nullify the cost of adding the product to the order.
FirstOrder
ItemTotal
Product
User
UserLoggedIn
One Use Per User
Taxon(s)
Country
match_policy
attribute on the Promotion
object. As you will see in the Admin, you can set the match_policy to be “any” or “all” of the rules associated with the Promotion. When set to “any” the Promotion will be considered eligible if any one of the rules applies, when set to “all” it will be eligible only if all the rules apply.