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):

• Buy X pay Y

• Fixed amount

• Fixed price

• Free gift

• Free shipping

• Percentage discount

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.

When fetching a list of promotions with sales channel API credentials, you'll get in the response all the active promotions associated with the market in scope, 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 flex promotions, custom promotion rules, etc.).

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:

1. Percentage discount

2. Free shipping

3. Buy X pay Y

4. Free gift

5. Fixed price

6. External promotion

7. Fixed amount

8. 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):

1. Exclusivity

2. Custom priority

3. Default priority (by type)

4. Activation date (based on the starts_at attribute)

A way to check the order of application of multiple promotions is to check the weight attribute, which is computed based on all the above-mentioned parameters — exclusivity, priority, type and start time. Promotions with higher weight apply first.

Remeber that negative adjustment 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).

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.

Data model

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 single promotion object. For the full set of available CRUD actions to the specific promotion type endpoints.