Setting up a promotion in the Promotion Engine involves defining when and how the promotion should apply, which products it targets, and what kind of benefit it provides. The different promotion types offer different configuration options, but the general structure of the configuration process is the same.
This page will guide you through the main configuration steps for common settings of all promotion types, as well as type-specific settings.
To access the configuration page, navigate to the Modules menu and search for the Promotions module. The page will open to a list of promotions that are already set up, displaying the following information:
Name | The name of the promotion, followed by its ID and status, which can be |
Type | The type of promotion. Find detailed information about the types below. |
Currency | The currency of the promotion. |
Recurring | Indicates whether the promotion is recurring or not. |
Start Date | Start date of the promotion. |
End Date | End date of the promotion. |
Application Count Limit | Maximum number of applications within one cart. |
Exclusive | Indicates whether the promotion can be applied together with other promotions. |
Setting up a new promotion
To access and display the configured information on customer interfaces, your developers need to implement the necessary calls throgh the Promotion Engine API.
Click the + Create new Promotion option in the sidebar
Promotion types
Click the type of promotion you want to add
Bonus Products: Add extra products for free when a customer buys a qualifying item (e.g., Buy shampoo, get a free conditioner).
Bundle: Offer a set of related products together at a discounted total price (e.g., T-shirt + jeans for 20% less).
Buy X for Total Y: Let customers buy a specific quantity of items for a fixed total amount (e.g., 3 socks for $10).
Buy X Get 1 Free (Bogo): Give one item for free or at a reduced price after a certain quantity is purchased (e.g., Buy 2 notebooks, get 1 free).
Cross Selling: Recommend discounted complementary products when a customer adds a main item to their cart (e.g., Add a phone and get 30% off a charger).
Free Sample: Include a small-sized product with the order to let customers try it for free (e.g., Free skincare sachet with any purchase).
Price Reduction: Apply a direct discount to a product’s price (e.g., 20% off selected shoes).
Product Set: Allow customers to choose a combination of products from a defined set at a special price (e.g., Buy coat & scarf set, get 12% off).
Promo Code: Let customers enter a code at checkout to unlock discounts or gifts (e.g., Use SPRING15 for 15% off).
Promotional Pricing: Temporarily reduce the price of items to drive sales (e.g., Weekend sale: coffee maker for $50).
Core Settings
Promotion Name
Enter a unique, descriptive name for the promotion. Must be unique across active promotions. Archived promotions can have duplicate names.Promotion Description
An optional field to add notes or explanations about the promotion.Image URL
Provide a direct, publicly accessible URL to an image representing the promotion (e.g.,https://example.com/image.jpg).Currency
Select the currency in which the promotion applies. Only carts with this currency will qualify for the promotion (e.g., Euro (EUR)).
.png)
Promotion Stacking
Promotion Stacking controls how promotions behave when multiple promotions are eligible in the same cart. Use these settings to define whether a promotion can apply multiple times and how it interacts with other promotions.
Self Stacking
Enable this to allow the promotion to be applied multiple times in one cart if the conditions are met repeatedly. If disabled, the promotion applies only once per cart.Self Stacking Limit
If you enabled Self Stacking, specify the maximum number of times the promotion can be applied in a single cart. Leave blank for unlimited applications.Stacking Type
Choose how this promotion can be combined with others:Exclusive: Cannot be combined with any other promotions.
Stackable: Can be combined with all other promotions.
Selective Stackable: Can be combined with other promotions except those you select as excluded below.
Excluded Promotions
If you choose Selective Stackable, select the promotions that cannot be used together with this promotion. You can select multiple active promotions by searching for their ID or name.
Restrictions
Minimum Total Before Tax
Set the minimum cart total (before tax) required for this promotion to apply. If the cart value is below this amount, the promotion will not activate.
Note: Changes made after activation will only affect future cart requests.Maximum Total Before Tax
Set the maximum cart total (before tax) for the promotion to be valid. If the cart exceeds this amount, the promotion won’t apply.
Note: Updates after activation apply only to new cart requests.Store Group
Enter one or more store groups where the promotion is valid. The promotion will only apply if the cart request includes one of these store groups.
Note: At least one store group must be specified. Changes take effect on future cart requests.Store
Optionally, select specific stores or enter their IDs where the promotion applies. Leave empty to apply promotion without specific store restrictions. Note: Changes apply to subsequent cart requests.
Timing
The Timing Settings define when your promotion is active and for how long.
Recurring
Enable this option if you want the promotion to repeat on a schedule.
Start Date
Set the date and time when the promotion becomes active. The time is interpreted according to the timezone configured under General Settings.
For one-time promotions, this is the exact start moment.
Example: If the Start date is May 1, 2025, 06:00, the promotion will start at this time.If you enabled the recurring option, this sets the first start; future active periods are calculated from this time based on recurrence rules.
Example: If the Start date is May 1, 2025, 06:00 and the Frequency is weekly on Mondays, the first active occurrence will be May 5, 2025, 06:00.
End Date
Set the date and time when the promotion ends. The time is interpreted according to the timezone configured under General Settings.
For one-time promotions, this is the exact end moment.
If you enabled the recurring option, this marks the end of the first recurrence.
Recurring Frequency (required if Recurring is enabled)
Choose how often the promotion repeats, e.g., daily, weekly, monthly, yearly, or more specific options like weekly on selected days.
Recurring Interval (required if Recurring is enabled)
Specify how often the recurrence repeats, such as every 2 weeks or every 3 months.
Recurring Days (for weekly select days recurrences)
Select the weekdays when the promotion should be active.
Recurring Months (for selected months recurrences)
Select which months the promotion should be active.
End Date of Recurrence (required if Recurring is enabled)
Set the final date the promotion will be active in the recurring schedule. The time is interpreted according to the timezone configured under General Settings.
Example: if the promotion repeats every Friday but the end date is set to a Wednesday, the last active Friday will be the Friday before that Wednesday.
Application Limit and Reset
This section allows you to control how many times a promotion can be used in total. Once this limit is reached, the promotion cannot be applied anymore, however, the reset feature allows the usage count to start over periodically (for example, every week or month), so the promotion can become available again after reaching the limit.
Application Limit
Enable this option to restrict the total number of times the promotion can be applied across all users.Maximum Applications
Set the maximum total number of times the promotion can be used. Leave empty or zero for unlimited use.
This count includes all users. You can update this value even after the promotion is activated.Reset Schedule
Enable this option to reset the application count based on a regular schedule. This only works if a maximum application limit is set to a non-zero value.First Reset Date
Define the exact date and time when the first application count reset will occur. The time is interpreted according to the timezone configured under General Settings.Reset Frequency
Choose how often the application count should reset (e.g., daily, weekly).Reset Interval
Specify the interval count for the reset frequency (e.g., every 2 weeks, every 3 days).
Example:
If you want the promotion to be used a maximum of 50 times every week, and reset the count every Monday at 8:00 AM:
Application Limit: 50
Reset Schedule: enabled
First Reset Date: April 28, 2025, 08:00 (this date is a Monday)
Reset Frequency: Weekly
Reset Interval: 1 week
.png)
Product selection settings
In this section, you define the specific products, categories, or item types that determine when a promotion applies. By selecting and configuring these criteria, you control which items in the cart trigger or qualify for the promotion.
The available settings differ based on the promotion type.
Bonus Products
Products
Enter the specific product(s) along with the required quantities that must be added to the cart to qualify for the promotion. You can specify multiple products and their quantities to set complex eligibility conditions.Categories:
Similar to products, you can define entire product categories that the customer’s cart must contain for the promotion to apply.
Specify the category ID(s) and the minimum quantities required. This is useful when you want to apply the promotion broadly to groups of products without listing each individually.Item Matching Rule
Choose how the system evaluates the presence of the listed products and categories in the cart.All: Every product and category listed must be present in the cart with the specified quantities to activate the promotion.
Any: The promotion is triggered if any one of the listed products or categories (with the required quantity) is found in the cart.
.png)
Product Set
Categories
Add product categories with respective quantities in the set. Use the Add item + button to build a category-based selection.
This is especially useful when the promotion should apply to a wide group of items. Categories can be used on their own or together with individual products to build a flexible and comprehensive product set.Products
Enter individual product(s) and the quantity to include in the product set. Click Add item + to include multiple items.
This is useful when you want to apply the promotion only to specific products. These products will be considered for the promotion regardless of their category, but this can be combined with category-based selections as needed.
Price Reduction
Products
Enter product(s) that should trigger the price reduction using the multi-select field.These products must be in the cart for the discount to apply.
Categories
Enter one or more product categories using the multi-select field to include all products from those categories for the price reduction.
This is useful when the price reduction should affect broader groups of products. You can combine category selections with individual product entries for more precise control.
Bundle
Products
Enter one or more products included in the bundle using the multi-select field.
This lets you specify exactly which products are part of the bundle.Categories
Enter one or more product categories using the multi-select field to include all products from those categories in the bundle.
Use this to cover larger groups of products without listing each individually. Categories and products can be combined for precise bundle definition.
Buy X For Total Y
Item Type
Select the type of item the promotion applies to (either Product or Category) using the dropdown. Only one option can be selected.
This determines if the promotion targets individual products or entire categories.Item Id
Enter the specific product or category depending on the selected Item Type. This is the item that the promotion will apply to and must be present in the cart.Quantity
Define the required quantity of the selected product or category items that must be in the cart for the promotion to be applicable.
The promotion activates only if the cart contains at least this number of the specified item(s).
Buy X Get One Free (BOGO)
Item Type
Choose whether the promotion applies to a Product or a Category using the dropdown. Only one option can be selected.
This defines whether the promotion targets individual products or whole categories.Item Id
Enter the specific product or category that the promotion applies to. This item must be present in the cart for the promotion to trigger.Quantity
Define the minimum number of specified items required in the cart to activate the promotion.
The promotion applies when the cart contains at least this quantity.
Cross Selling
Products
Enter the product(s) to which the cross-selling promotion should be applied. Use the multi-select field to choose one or more specific items.These products must be in the cart for the discount to apply.
Categories
Enter one or more product categories using the multi-select field to include all products from those categories in the product selection.
This is useful when the promotion should affect broader groups of products. You can combine category selections with individual product entries for more precise control.
Free Sample
Products
Enter products along with the required quantities that must be added to the cart to qualify for the promotion. You can specify multiple products and their quantities to set complex eligibility conditions.Categories:
Similar to products, you can define entire product categories that the customer’s cart must contain for the promotion to apply.
Enter the category ID(s) and the minimum quantities required. This is useful when you want to apply the promotion broadly to groups of products without listing each individually.Item Matching Rule
Choose how the system evaluates the presence of the listed products and categories in the cart.All: Every product and category listed must be present in the cart with the specified quantities to activate the promotion.
Any: The promotion is triggered if any one of the listed products or categories (with the required quantity) is found in the cart.
Promotional Pricing
Products
Enter one or more products that the promotional price should be applied to, using the multi-select field.
The promotion triggers only if these specific products are present.Categories
Enter one or more product categories using the multi-select field to apply the promotional price to all items in those categories.
This broadens the promotion to apply when any products from the selected categories are included.
Promo Code
Promo Code
Enter the exact code customers must use at checkout to redeem the discount. This code triggers the discount when applied.Excluded Products
Select products that the promotion should not apply to, or manually enter their product IDs.If left empty, the promotion applies to all products in the cart unless restricted elsewhere.
Use this to exclude specific items from the discount, such as products already on sale or items not eligible for this promo.
Discount settings
In this section, you define how the discount is applied once a cart qualifies for the promotion.
Discount configurations differ based on the promotion type.
Bonus Products
Products
Enter the products to be given as bonus items and specifying quantities.
Click Add item + to include multiple bonus products and quantities.Discount Value
Define the price that will be used for the bonus products in promotion calculations.
Leaving this field empty will treat bonus items are free (price set to 0).
.png)
Product Set
Item Selection Strategy
Choose how the system selects items within the product set when multiple eligible products are in the cart.Cheapest: The discount applies to the least expensive item(s) in the set.
Most expensive: The discount applies to the highest-priced item(s).
Discount Type
Define the nature of the discount to be applied to the product set. Options include Percentage, Fixed discount, and Group price.Discount Value
Enter the discount amount or percentage, depending on the selected discount type. This value determines the actual reduction or new price applied within the promotion.
.png)
Price Reduction
Discount Type
Define how the discount should affect item pricing. You can choose from Percentage, Fixed discount, and Fixed price for each item.Discount Value
Enter the amount or percentage according to the selected discount type.
This value controls how much the customer saves or what price they will pay for each discounted item.
Bundle
Discount Type
Select the method used to calculate the discount on the entire bundle. Options include Percentage, Fixed discount, and Fixed price for the bundle.Discount Value
Enter the discount amount or percentage, depending on the selected type.
This value determines how the system adjusts the total cost of the bundle for the customer.
.png)
Buy X For Total Y
Group Price Before Tax
Define the total price (excluding tax) that the selected items will cost when the promotion is applied. Currency is automatically applied based on the promotion Currency setting.Item Selection Strategy
Choose how the eligible items are selected when multiple matching items are in the cart:Cheapest: The lowest-priced items will be grouped to receive the total price.
Most expensive: The highest-priced items will be grouped for the offer.
Buy X Get One Free (BOGO)
Item Selection Strategy
Define how the system selects which eligible item(s) are given for free when multiple eligible products are in the cart:Cheapest: The lowest-priced eligible item(s) will be given for free.
Most expensive: The highest-priced eligible item(s) will be given for free.
Quantity
Enter how many items should be given for free when the promotion is triggered.
Cross Selling
Item Selection Strategy
Determines which product(s) will receive the discount if more than one qualifying cross-sell item is in the cart:Cheapest: The lowest-priced cross-sell item is discounted.
Most expensive: The highest-priced cross-sell item is discounted.
Categories
Enter the category(s) the discount should apply to and configure:Discount Type: As above – Percentage, Fixed discount, or Fixed price
Discount Value: The discount amount or percentage.
Use Add item + to set up multiple category-level discount rules.
Products
Enter the product(s) the discount should apply to and configure:Discount Type: Choose how the discount is applied. Options include Percentage, Fixed discount, and Fixed price for the item.
Discount Value: The amount or percentage based on the selected discount type.
Use Add item + to define multiple products with separate discount settings.
.png)
Free Sample
Product
Enter the product to be added as a free sample. Only one product can be selected for each promotion.Quantity
Define how many units of the selected product will be added to the cart as free samples.Discount Value
Set the price for calculation purposes (e.g., when determining the overall promotional value).
If left blank, the free sample will be considered fully discounted (price = 0).
Promotional Pricing
Unit Price Before Tax
Enter the new unit price (excluding tax) that will override the original price for the affected product(s).
Only one fixed price can be set per promotion. If different prices are needed for different products, create separate promotions. Currency is automatically applied based on the promotion Currency setting.
Promo Code
Discount Type
Select the type of discount applied by the promo code. Options include Percentage, Fixed discount, and Fixed price.Discount Value
Enter the discount amount or percentage, depending on the selected type.
This value determines how the system adjusts the total cost if the promo code is applied.
Saving and activating a promotion
Once you’ve entered all the required information for the promotion, save your settings by clicking the Save button at the bottom of the setup page. Initially, the promotion will be saved as a draft, meaning it won’t be applicable to customers’ carts, the promotion will only appear in the list of promotions. After saving your new promotion, you can activate it immediately by clicking Set to active on the upper right-hand side of the promotion setup page.
Managing promotions
Edit a promotion
Go to the Promotions tab
Click the Edit option under the hamburger button on the row of the promotion you’d like to edit
Change the settings as needed
Save your changes by clicking Save at the bottom of the page
Archive a promotion
You can delete activated promotions from the Management UI by archiving them.
Go to the Promotions tab
Click the Edit option under the hamburger button on the row of the promotion you’d like to archive
Click the Set to Archived button on the upper right-hand side of the page
Archiving is irreversible. Once a promotion is archived, it cannot be restored. Archived promotions are accessible within the Retention Period, then archived promotions are permanently deleted.
The status update endpoint of the Promotion Engine API can also be used to archive a promotion.