API reference

External promotions

The external 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.
Besides the promotion types that are supported out-of-the-box Commerce Layer lets you integrate any kind of promotional engine as an external promotion. When triggered, external promotions are responsible for adding the externally computed discount to the orders invoved. When an external promotion activates, Commerce Layer triggers a POST request to the promotion URL endpoint, sending the order payload (including its line items) in the request body. The external service response (or error) must match the format described in this example.

Application scope

External promotions are defined by currency code and can be restricted to a specific active market (in which case the currency code is inherited by the market's price list). Within the time window given by their activation and expiration dates, external promotions that have not reached their total usage limit are considered active. If no promotion rule is associated with an active external promotion, the computed discount is applied to:
  • All the orders in the specified currency, if 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.
Multiple external promotions can be applied to the same order, even concurrently with other promotion types (based on their priority and up to the involved items amount saturation), as long as you don't reach the maximum number of active promotions allowed for your organization.

Discount calculation and distribution

If associated with an SKU list, the total discount due to external promotions is calculated and distributed on the matching line items of type skus or bundles belonging to that list. Otherwise, on all the taxable items of the order. In both cases the discount distribution is based on the ratio between the line item amount and the sum of the amounts of all the line items to which the promotion is applied.
Check the related guide for any additional info on how to configure your external promotion engine and integrate it with Commerce Layer.