Promotions
The promotion object and the allowed CRUD operations on the related resource endpoint
Last updated
The promotion object and the allowed CRUD operations on the related resource endpoint
Last updated
Commerce Layer provides a promotional engine built on top of two main resources: promotions and .
At the moment, the following promotion types are available (more to come):
You can also create promotions based on . If your promotion strategy is quite complex and need unparalleled flexibiliy to cover a wider range of use cases, check our (still in closed beta — official public release coming soon). For any other cases, evaluate the option to leverage .
Promotions are defined by currency code (except for buy X pay Y, free gift, free shipping, percentage discount, and external promotions which can be applied cross-currencies) and can be restricted to a specific active market (in which case the currency code is inherited by the market's price list). Flex promotions application scope is defined by the conditions and actions provided in the associated rules.
When triggered, promotions are responsible for adding a discount (based on the promotion type) to the orders involved. Within the time window given by their activation and expiration dates, promotions that are and have not reached their total usage limit are considered active.
If no promotion rule is associated with an active promotion, the related discount is applied to:
All the orders, if the promotion is not restricted to a specific currency or market.
All the orders in the specified currency, if a currency code is specified but the promotion is not restricted to a specific market.
All the orders of the market in scope, if the promotion is attached to a market.
Otherwise, if one or more promotion rules are defined, the promotion is triggered only when it matches all of them.
Except for the case where you need them to be associated with a coupon, when using flex promotions you're not required to define any promotion rule, set a currency code, or associate a specific market. Flex promotions application scope is defined by the conditions and actions provided in the associated rules.
Newly created promotions are enabled by default. You can disable them by passing the _disable
trigger attribute and eventually re-enable them by passing the _enable
trigger attribute. Disabled promotions are not applied, even if they match their activation rules.
If multiple promotions are active at the same time you can decide in which order you need them to be applied and specify a custom priority by setting the priority
attribute of each single promotion, which must be an integer number greater than 0 (the lower the number, the higher the priority). If no custom priority is defined (or in case of promotions with the same custom priority) a default priority will be considered and the concurrent promotions will be applied by type according to the following order:
Percentage discount
Free shipping
Buy X pay Y
Free gift
Fixed price
External promotion
Fixed amount
Flex
To compute the total discount in case of multiple concurrent promotions the following parameters are taken into account, in order of importance (meaning that if one of them is not defined or doesn't help to define the prioritization the one immediately following is checked):
Custom priority
Default priority (by type)
Activation date (based on the starts_at
attribute)
The number of promotions associated with a is unlimited. The number of promotions associated with any other promotion is limited to a maximum of 10 active promotions per organization's environment, regardless of their type (this limit may vary depending on your plan). Please note that you can create and enable as many promotions as you want but, if more than 10 promotions are active at the same time, only the 10 that have higher will be applied.
When fetching a list of promotions with API credentials, you'll get in the response all the active promotions associated with the , or (if no market is in scope) with the currency code of the price list in scope, plus all promotions that aren't associated with any market and currency code (e.g. involving , , etc.).
To make a promotion exclusive you just need to set the exclusive
attribute to true
. When an exclusive promotion is triggered no other concurrent promotion will be applied. In case of multiple exclusive concurrent promotions, the one with the highest will be applied.
Remeber that negative amounts are applied before any kind of promotion (e.g. if you add an adjustment that brings the total order amount to zero, no promotion will have any effect).
The total discount due to the application of one or more promotion(s) is distributed across the order's according to different logic based on the promotion type. If the discount affecting a line item is greater than the line item's total amount, only the part of the discount that contributes to saturating the amount is applied. If multiple discounts affect the same line item and their sum is greater than the line item's total amount, only the ones due to promotions with higher priority are applied up to the amount saturation (the last one could be partially applied), after which the next-in-line discounts (i.e. due to promotions with lower priority) won't be applied.
Check the related and explore the flowchart that illustrates how the promotion resource relates to the other API entities.