Buy x pay y promotions
The buy X pay Y promotion object and the allowed CRUD operations on the related resource endpoint
Last updated
API reference
The buy X pay Y promotion object and the allowed CRUD operations on the related resource endpoint
Last updated
Commerce Layer provides a promotional engine built on top of two main resources: and .
When triggered, buy X pay Y promotions are responsible for adding a discount to the orders involved. The related discount amount is computed based on the associated SKU list: for each SKU in the order that belongs to the list and has a quantity equal to any multiple of the x attribute, a discount is applied as if the purchased quantity of the same SKU was decreased down to the same multiple of the y attribute. Basically, customers that add to cart a number greater than or equal to n*x (and less than (n+1)*x) units of a specific product pay only for n*y units of the same product, thus getting n*(x-y) units for free — where x must be greater than y (and n greater than zero). The corresponding stock is updated consistently (i.e. decreased by n*x units).
Let's consider an example where a buy X pay Y promotion (with X=3 and Y=2) is associated with an SKU list containing the products A, B, and C. Some of the possible scenarios are the following:
If customers add to cart 3 units of product A, they pay for 2 and get 1 of them for free.
If customers add to cart 6 units of product A and 3 units of product B, they get 2 units of product A and 1 unit of product B for free.
If customers add to cart 7 units of product A, 4 units of product B, and 2 units of product C, they get 2 units of product A and 1 unit of product B for free.
If customers add to cart 5 units of product A, 2 units of product B, and 8 units of product D (which is not in the associated SKU list), they get 1 unit of product A for free.
If customers add to cart 2 units of product A and 4 units of product D (which is not in the associated SKU list), the promotion doesn't apply and they get no discount.
If you set the cheapest_free attribute to true (default is false) the buy X pay Y promotion type behaves differently. In this case, the value of the x attribute is matched against the sum of the quantities of all the SKUs in the associated list. If the order contains some of the SKU belonging to the list and the sum of their quantity is equal to any multiple of x (i.e. n*x), the customer will pay only for the most expensive n*y, thus getting the n*(x-y) cheapest ones among those SKUs for free.
Considering the same example as above in the case of a cheapest free buy X pay Y promotion (let's assume that A is the most expensive and C the cheapest of the three products), the aforementioned scenarios could now lead to different discounts:
If customers add to cart 3 units of product A, they pay for 2 and get 1 of them for free.
If customers add to cart 6 units of product A and 3 units of product B (9 units of products belonging to the list in total), they get all 3 units of product B for free.
If customers add to cart 7 units of product A, 4 units of product B, and 2 units of product C (13 units of products belonging to the list in total), they get 2 units of product B and all 2 units of product C for free (4 units for free in total).
If customers add to cart 5 units of product A, 2 units of product B, and 8 units of product D (7 units of products belonging to the list in total), they get all 2 the units of the product B for free.
If customers add to cart 2 units of product A and 4 units of product D (2 units of products belonging to the list in total), the promotion doesn't apply and they get no discount.
Buy X pay Y 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, buy X pay Y promotions that have not reached their total usage limit are considered active. If no promotion rule is associated with an active buy X pay Y 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.
The total discount due to buy X pay Y 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.
Multiple buy X pay Y promotions can be applied to the same order, even concurrently with other promotion types (based on their and up to the involved items amount ), as long as you don't reach the maximum number of active promotions allowed for your organization.