---
title: Working with Buy X Get Y discounts
related:
- https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts/working-with-buy-x-get-y-discounts/example-applying-a-buy-x-get-y-discount-1.md
- https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts/working-with-buy-x-get-y-discounts/example-applying-a-buy-x-get-y-discount-2.md
- https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts/working-with-discount-coupons/coupons-and-buy-x-get-y-discounts.md
- https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/checkout-process/reference-checkout-process-web-parts/configuring-the-shopping-cart-totals-web-part.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Buy X Get Y discounts in Kentico E-commerce Solution are a cross-selling tool which allows you to increase sales of chosen products. The **Buy X Get Y discounts** application facilitates a number of shopping scenarios, such as:
- buy some of specified products, get the cheapest product for free, e.g., buy 3 pieces of clothes, get the cheapest one for free, or
- buy some of specified products, get a specific other product for free or with a discount, e.g. buy a computer, get _Steve Jobs (E-book)_ for free, or buy _Adidas Zebra Crew T-Shirt_, get one more with a 50 % discount.
To set up a basic Buy X Get Y discount:
1. Open the **Buy X Get Y discounts** application.
2. Click **New Buy X Get Y discount**.
3. Type a **Name** for the discount.
4. Specify "**Buy" conditions**. Buy conditions indicate the products that customers need to add to their shopping cart to be eligible to get products for free or with a discount.
- **Buy any**– select _products_ to select individual products; select _products in departments_ to select specific departments.
- **Products** or **Departments** – depending on your choice in **Buy any**, click **Select products** or **Select departments** to select either products or departments.
- **Minimum unit quantity** – specify how many units customers need to add to their shopping cart to be eligible for the discount.
5. Specify "**Get" conditions**. Get conditions define what products customers get for free or with a discount.
- **Get** – select _cheapest unit for discounted amount_ to automatically apply the discount to the cheapest product from the set specified in **"Buy" conditions**; select _specific product for discounted amount_ to define a product that will be added to the customer's order as a gift.
- **Specific product** – appears if you selected _specific product for discounted amount_ in **Get**.
- **Discount** – select _percentage_ to apply the discount in percent or _fixed amount_ to apply the discount in a specific amount of money in the [main currency](https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/configuring-currencies.md).
- **Amount** – specify an exact value of the discount either in percent or in fixed amount according to **Discount**.
6. Click **Save**.
Now, you have a completed **Buy X Get Y discount**. Whenever a customer fulfills **"Buy" conditions**, they will get the discount which you have just specified in **"Get" conditions**. You can find the newly added discount with the lowest priority (the highest number) at the end of the Buy X Get Y discount list. To create more complex Buy X Get Y discount, [see all parameters below](#reference).
> **Info:** If you edit or delete a discount, the existing orders stay with that discount. To update existing orders according to the new rules, you must edit the required orders manually.
## Buy X Get Y discounts shopping examples
Example 1 – **buy one item, get another one free** (in other words, buy two items for the price of one): Customer adds two pairs of jeans to their shopping cart. The system automatically applies a 100% discount on one of the items. If a customer adds only one pair of jeans to their shopping cart, another pair is **not** added automatically.
Example 2 – **buy multiple items, get the cheapest one free**: Customer adds multiple different books to the shopping cart. The system evaluates which item has the lowest price (before applying other discounts) and applies a 100% discount on that item. [See a specific example](https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts/working-with-buy-x-get-y-discounts/example-applying-a-buy-x-get-y-discount-2.md). The example is also applicable with a discounted product instead of a free one.
Example 3 – **buy one item, get a gift**: Customer adds a tennis racket to their shopping cart. The system automatically adds a pack of tennis balls (with 100% discount) to the shopping cart. If the customer adds the balls first and then the racket, the system applies a 100% discount on the set of balls which has already been added. [See a specific example](https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts/working-with-buy-x-get-y-discounts/example-applying-a-buy-x-get-y-discount-1.md).
> **Note:** The system adds products to the shopping cart automatically only if you set the "Get" condition of the particular Buy X Get Y discount to "specific product" and select the **Add product to cart automatically** field.
> **Note:** Customer is not notified that they have an opportunity to purchase a discounted product if so. To notify them you can [create a new webpart](https://docs.kentico.com/k9/custom-development/developing-web-parts/creating-new-web-parts.md).
## Changing Buy X Get Y discount priority
Buy X Get Y discounts are applied based on their priority. The discount priority is stated with a number. The lower the number is, the higher priority the discount has.
1. Open the **Buy X Get Y discounts** application.
2. Click on the number in the column **Priority** in the row of a discount.
3. Change the number to the desired one. The number must be greater than one.
> **Tip:** Use greater intervals between priority numbers. If you want to add a new discount inbetween two already existing, you can add the new discount more easily between 10 and 20 than between 1 and 2. If you already have only small gaps, you can also use decimals.
4. Press **Enter** or click on the green confirmation button () next to the number.
5. (Optional) Edit () individual accounts and change the **Apply lower priority discounts**as necessary. If cleared, no other Buy X Get Y discounts are applied to the shopping cart.
Buy X Get Y discounts are now applied based on the priority that you assigned to them. Note that other [discounts](https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts.md) of a different type (e.g., volume discounts, product discounts) are still applied.
### Example – Buy X Get Y discount priority
You want to set 10 % discount to any book and additional 5 % discount to bought _Steve Jobs (E-book_).
1. Create a new discount for any book.
- **Name**: Buy a book, get 10 % off
- **Buy any**: products in departments
- **Departments**: Books
- **Amount**: 10 %
2. Set the priority of the created book discount to _20_.
3. Create a new discount for _Steve Jobs (E-book)_.
> **Info:** The system doesn't sum Buy X Get Y discounts to the same product. If you want to have an additional discount to a product, you have to create a new discount with the total discount amount and assign it a higher priority (a lower number).
- **Name**: Buy Steve Jobs, get 15 % off
- **Products**: Steve Jobs (E-book)
- **Amount**: 15 %
- That is 10 % for any book and the additional 5 % discount for _Steve Jobs (E-book)_.
4. Set the priority of the created Steve Jobs discount to 10.
Now, when you put a book to the shopping cart, the first discount for books applies. When you put _Steve Jobs (E-book)_ to the shopping cart, the second discount applies.
## Displaying Buy X Get Y discounts data on pages, in invoices, and e-mails
You can use the **Shopping Cart Totals** web part with transformations to [display Buy X Get Y discounts on a page](https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/checkout-process/reference-checkout-process-web-parts/configuring-the-shopping-cart-totals-web-part.md), e.g., in the shopping cart. To promote Buy X Get Y discounts on various pages, you can also use your custom web parts.
In invoices and e-mailes, you can use the following macros to display Buy X Get Y discount data. Note that in code Buy X Get Y discounts (along with order discounts) are called _OrderRelatedDiscountSummaryItems_.
- **OrderRelatedDiscountSummaryItems** – a collection of Buy X Get Y discounts and order discount applied to items in a particular shopping cart instance. The collection's items hold following values:
- **Value** – the amount saved after applying the discount, e.g., 50 % of the price of a product.
- **Name** – the name of the discount as specified in the Buy X Get Y discounts application.
To extract the value-name pairs from the OrderRelatedDiscountSummaryItems collection, use the following macro:
```csharp
{% OrderRelatedDiscountSummaryItems.ApplyTransformation("Ecommerce.Transformations.Order_OrderRelatedDiscountsContent", "Ecommerce.Transformations.Order_OrderRelatedDiscountsHeader", "Ecommerce.Transformations.Order_OrderRelatedDiscountsFooter") %}
```
The default installation of Kentico contains ready-to-use transformations with Buy X Get Y discounts in mind. The parameters of the ApplyTransformation method used in the code example are names of the default transformations. The default transformations are stored in the E-commerce transformations page type.
## Reference
| General | |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | The discount name that is displayed in the shopping cart, invoices, and e-mails. |
| Code name | The unique identifier of the discount object used by developers in the code.
Unless there is a reason to set a particular value, you can leave the default _(automatic)_ option, and the system generates an appropriate code name automatically. |
| Enabled | If selected, the discount is allowed to be applied. If cleared, the discount is disabled. |
| "Buy" Conditions | |
| Buy any | Sets what customer must add to the shopping cart to obtain the discount.
**Products** – allows you to choose individual products.
**Products in departments** – allows you to choose whole departments of products.
For example, if you set the discount to be applied when customer buys 3 products in **Minimum unit quantity** and you choose 6 products in this field, customer fulfills the "Buy" conditions whenever they put any combination of products in this field to the shopping cart. |
| Products | Appears when you select _products_ in **Buy any**.
Select specific product, or products. Customer can add any combination of the products to the shopping cart to fulfill the "Buy" conditions. |
| Departments | Appears when you select _products in departments_ in **Buy any**.
Select specific department, or departments. Customer can add any products from the selected department, or departments to fulfill the "Buy" conditions. |
| Minimum unit quantity | Specify how many units customers need to add to their shopping cart to be eligible for the discount.
For example, type 2 when:
The customer adds 2 products to the shopping cart, and gets another product for free.
The customer adds 3 products to the shopping cart, and one of them gets a discount. |
| "Get" Conditions | |
| Get | Select what customers get if they fulfill **"Buy" conditions**.
**Cheapest unit for discounted amount** – the cheapest unit from the selected products customer added to the shopping cart gets the discount.
**Specific product for discounted amount** – the system adds a specific product to customer's shopping cart, or customers have an option to add a specific product to their shopping cart for a discounted price. |
| Specific product | Appears when you select _specific product for discounted amount_ in **Get**.
Select specific product which gets the discount. |
| Discount | Specify if you want to apply the discount in percentage or in fixed amount.
**Percentage** – the cheapest unit or the product according to **Get** gets the discount in percentage of its price.
**Fixed amount** – the cheapest unit or the product according to **Get** gets the discount in a specific amount of money in the on-line store [main currency](https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/configuring-currencies.md). |
| Amount | Specify an exact value of the discount in percent or in fixed amount according to **Discount**.
The amount has to be a number. When the amount is in percentage, enter a number between 0 and 100. When the amount is fixed, enter a number greater than 0. |
| Add product to cart automatically | Appears when you select _specific product for discounted amount_ in **Get**, and when **Amount** is 100 %.
If selected, the system adds the specified product to the shopping cart automatically when the shopping cart fulfills the **"Buy" conditions****Note:** If you choose a specific product to be added automatically to the customer's order as a gift, the system won't add the product when:
you choose a product with [product options](https://docs.kentico.com/k9/e-commerce-features/managing-your-store/products/working-with-product-options.md) (but you can choose a product variant), or
the discounted product is not allowed for sale, or
the discounted product is allowed to be sold only if items are available and there is no available item left.**Info:** Customer cannot remove an automatically added product if they are entitled to it. If they try to remove the product, the system will add it again immediately. |
| Coupons | |
| Customer has to redeem a coupon to get the discount | If selected, only customers who type valid coupon code are able to apply the discount.
You can set coupons on the **Coupons** tab in the left menu. After enabling the field and saving the discount, you will be redirected there automatically.
More info about working with coupons is to be found in [separate page](https://docs.kentico.com/k9/e-commerce-features/managing-your-store/discounts/working-with-discount-coupons/coupons-and-buy-x-get-y-discounts.md).
**Examples**
The examples show how the auto-adding feature works if the discount is coupon-based.
**Example 1:**
Customer adds X to the cart, Y is not auto-added.
Customer types coupon code, Y is auto-added.
Customer removes coupon code, Y is auto-removed.
**Example 2:**
Customer adds X to the cart, Y is not auto-added.
Customer adds Y.
Customer types coupon code, Y in the shopping cart is recalculated as free.
**Example 3:**
Customer types coupon code.
Customer adds X to the cart, Y is auto-added. |
| Duration | |
| Valid from | Specify from when the discount is running.**Info:** If you leave **Valid from** empty, the discount will be valid permanently till **Valid to**. |
| Valid to | Specify to when the discount is running.**Info:** If you leave **Valid to** empty, the discount will be valid permanently from **Valid from**. |
| Target customers | |
| Available for | Choose [roles of users](https://docs.kentico.com/k9/managing-users/role-management.md) who are able to apply the discount:
**All visitors** – all customers are eligible for the discount.
**Registered users** – only registered customers are eligible for the discount.
**Registered users in selected roles** – only registered customers in selected roles are eligible for the discount. To add roles:
Click **Select roles** to open the **Select roles** dialog.
Select the required roles.
Click **Select**.**Tip:** You can enter roles directly by typing in their code names separated by semicolons, e.g., _\_authenticated\_;Members_.**Tip:** You can add registered customers to roles in the **Customers** application while editing a selected customer on the **Roles** tab. |
| Discount processing | |
| Apply lower priority discounts | If selected, other Buy X Get Y discounts with lower priorities are applied to the shopping cart as well. If cleared, discount processing stops with this discount. |
| Limit use per order | Set how many times customer is allowed to apply the discount in one order.
**Example**
Example with **Minimum unit quantity** set to 2 and a **100% discount** to the **cheapest** product.
Customer adds 3 products to his shopping cart.
In the shopping cart, the system applies a 100% discount to the cheapest product.
If the customer adds another 3 products, they will have 6 products in total. When **Limit user per order** is set to unlimited, the system applies the discount twice, so the two cheapest products are for free. When **Limit user per order** is set to 1, the system applies the discount only once, so only the one cheapest product is for free. |
## Buy X Get Y discounts API
Buy X Get Y discounts are called MultiBuyDiscounts in the API. The API comprises the following objects:
- **MultiBuyDiscountInfo** – stores information about the discount
- **DiscountSummaryItem** – simplified view on the discount data, contains only the name and value of the discount
- **ShoppingCartInfo.OrderRelatedDiscountSummaryItems** property – collection of **DiscountSummaryItem** objects applied to products in the current shopping cart