Free gift promotions

The free gift 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.

When triggered, free gift promotions are responsible for adding a discount to the orders involved. The related discount amount is computed by setting to zero the price of the SKUs matching the associated list, based on the position and the quantities of the SKU list items within the SKU list. Please note that the discount is applied only when one of those SKUs is added to the order. It is possible to limit the free gifts by specifying a max_quantity (default to 1), which also honors the quantities and position of the list items.

Free gift promotions work only if associated with manual SKU lists. In order for free gift promotion to apply to bundles, the resources must share the same SKU list (in this case, there is no SKUs partial matching).

Let's consider an example where a free gift promotion is associated with an SKU list containing the products A (with quantity 2) and B (with quantity 1), in that order. Some of the possible scenarios are the following, based on the specified max_quantity:

• max_quantity = 1 (default)

  • If customers add to cart 1 or more units of product A, they get 1 of them for free.

  • If customers add to cart 1 or more units of product A and 1 or more units of product B, they get 1 unit of product A for free.

  • If customers add to cart 1 or more units of product B but none of product A, they get 1 unit of product B for free.

• max_quantity = 2

  • If customers add to cart 3 units of product A, they get 2 of them for free.

  • If customers add to cart 2 units of product A and 1 unit of product B, they get 2 units of product A for free.

  • If customers add to cart 1 unit of product A and 2 units of product B, they get 1 unit of product A and 1 unit of product B for free.

• max_quantity = 3

  • If customers add to cart 3 units of product A, they get 2 of them for free.

  • If customers add to cart 2 units of product A and 1 unit of product B, they get all them for free.

  • If customers add to cart 1 unit of product A and 2 units of product B, they get 1 unit of product A and 1 unit of product B for free.

Application scope

Free gift promotions can be optionally defined by currency code or restricted to a specific active market (in the latter case the currency code is inherited by the market's price list). Within the time window given by their activation and expiration dates, free gift promotions that have not reached their total usage limit are considered active. If no promotion rule is associated with an active free gift promotion, the 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.

Multiple free gift 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

The total discount due to free gift promotions is calculated and distributed on the matching line items of type skus or bundles belonging to the associated SKU list, according to the promotion logic.