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. For any other cases, evaluate the option to leverage external promotions.
Promotions are defined by currency code (except for buy X pay Y, free gift, free shipping, and percentage discount types 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). 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.
The number of promotions associated with a coupon code promotion rule is unlimited. The number of promotions associated with any other promotion rule is subject to limitations: by default, only a maximum of 10 active promotions per organization is allowed, 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.
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.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.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:- 1.Percentage discount
- 2.Free shipping
- 3.Buy X pay Y
- 4.Free gift
- 5.Fixed price
- 6.External promotion
- 7.Fixed amount
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):
- 1.
- 2.Custom priority
- 3.Default priority (by type)
- 4.Activation date (based on the
starts_atattribute)
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.
Check the related ER diagram and explore the flowchart that illustrates how the promotion resource relates to the other API entities.
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 modified 3d ago