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 involved. 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.

External promotions are subject to a circuit breaker check: if the call to your external endpoint fails consecutively more than 30 times, the circuit breaker opens and any further request to the resource will be skipped. You can check the circuit breaker current status by fetching the circuit_state and circuit_failure_count attributes or manually reset it by passing the _reset_circuit trigger (the circuit is anyway automatically reset anytime a call to your external endpoint succeeds before reaching the counter's threshold).

Application scope

External promotions can be optionally defined by currency code or 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, if the promotion is not restricted to a specific 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.

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.

If you want to distribute the external promotion discount only on specific line items, you can list their IDs in the line_items array of the response. You can also define specific discounts for different line items, as explained here.

How-to

Check the related guide for any additional info on how to configure your external promotion engine and integrate it with Commerce Layer.