Promotions within Spree are used to provide discounts to orders, offer free shipping or to add potential additional items at no extra cost (eg. samples).

Promotions are one of the most complex areas within Spree, as there are a large number of moving parts to consider. Although this guide will explain Promotions from a developer’s perspective, if you are new to this area you can learn a lot from the Admin > Promotions tab where you can set up new Promotions, edit rules & actions, etc.

Promotions can be activated in three different ways:

  • When a user adds a product to their cart (automatic promotions, eg. free shipping with a threshold)
  • When a user enters a coupon code during the checkout process
  • When a user visits a page within the Spree store (path-based promotions, eg. a promotion that offers a discount on a specific page)

Promotions for these individual ways are activated through their corresponding PromotionHandler class, once they’ve been checked for eligibility.

Promotions relate to two other main components: 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:

AttributeDescriptionExample Value
nameThe name of the promotionSummer Sale
descriptionA brief description of the promotionDiscounts for summer
expires_atThe expiration date and time of the promotion2025-09-01 23:59:59
starts_atThe start date and time of the promotion2025-06-01 00:00:00
codeA code that users can enter to apply the promotionSUMMER2023
usage_limitThe total number of times the promotion can be used500
match_policyThe policy for how promotion rules are matchedall
pathThe specific path that activates the promotion/summer-sale
per_code_usage_limitThe number of times a single code can be used1

Path-based promotions will only work when the Spree::PromotionHandler::Page class is used, as in Spree::ContentController from spree_rails_frontend gem


There are four actions that come with Spree:


Here’s a list of all the rules that come with Spree:

Rules are used by Spree to determine if a promotion is applicable to an order and can be matched in one of two ways: all of the rules must match, or one rule must match. This is determined by the 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.

Extending Promotions

Please follow our extending Promotions guide to learn how to create custom promotion rules and actions.

Was this page helpful?