Promotions
The promotion object and the allowed CRUD operations on the related resource endpoint
Commerce Layer provides a promotional engine built on top of two main resources: promotions and promotion rules.
At the moment, the following promotion types are available (more to come):
You can also create promotions based on coupons. If your promotion strategy is quite complex and need unparalleled flexibiliy to cover a wider range of use cases, check our flex promotions (still in closed beta — official public release coming soon). For any other cases, evaluate the option to leverage external promotions.
Application scope
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 enabled and have not reached their total usage limit are considered active.
If you set an expiration date also at the coupon level, the discount related to promotions associated with a coupon code promotion rule will be applied only if the associated coupon is not expired.
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.
The number of promotions associated with a coupon code promotion rule 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 priority will be applied.
Enabling / disabling promotions
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.
Exclusive promotions
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 priority will be applied.
Priority and order of application
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_atattribute)
Discount distribution
The total discount due to the application of one or more promotion(s) is distributed across the order's taxable line items 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.
This is an immutable API, meaning that create, update, and delete operations are not allowed on this endpoint. You can only fetch a list of promotions or a specific single one.
Last updated