--- title: Working with Buy X Get Y discounts related: - https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-coupon-codes.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 the Xperience 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 one of the following options: - **products** – for individual products - **products in sections** – for entire sections of the [product tree structure](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-products/configuring-product-structure.md) - **products in departments** – for entire [departments](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/categorizing-products/departments.md) - **products with brands** – for products with assigned [brands](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-brands-and-manufacturers.md) - **products in collections** – for products assigned to [collections](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-product-collections.md) - **Products / Sections / Departments / Brands / Collections** – depending on your choice in **Buy any**, select a list of either products, sections, departments, brands or collections. - **Minimum unit quantity** – specify how many product 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 as a percentage or _fixed amount_ to apply the discount in a specific amount of money in the [main currency](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-currencies.md). - **Amount** – specify an exact value of the discount either as a percentage or fixed amount according to **Discount**. 6. Click **Save**. You have now created a **Buy X Get Y discount**. Whenever a customer fulfills the **"Buy" conditions**, they get the discount which you specified in the **"Get" conditions**. You can find the newly added discount with the lowest priority 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:** **Effects of discount modification on already existing orders** > > If you edit or delete a discount, existing orders do not change and remain with the original discount. To update existing orders according to the new rules, you need to edit the 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): A 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**: A 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. The discount can also be less than 100%. Example 3 – **buy one item, get a gift**: A customer adds a tennis racket to their shopping cart. The system automatically adds a pack of tennis balls (with a 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. > **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. > **Tip:** Customers are not automatically notified when they have an opportunity to purchase a discounted product based on their current shopping cart content. To notify them, adjust the [content of your shopping cart pages](https://docs.kentico.com/13/e-commerce-features/developing-on-line-stores/implementing-a-checkout-process/integrating-the-shopping-cart.md). ## Changing Buy X Get Y discount priority Buy X Get Y discounts are applied based on their priority. The discount priority is determined by the order of items in the discount listing. The higher the discount is, the higher its priority. Priorities can be changed using drag-and-drop functionality. To change the priorities of your discounts: 1. Open the **Buy X Get Y discounts** application. - The discounts are ordered according to their current priority. 2. Drag a discount using the **Move** () area to a different position in the listing. ![Changing the discount priority](https://docs.kentico.com/docsassets/13/working-with-buy-x-get-y-discounts/changing_priority.png "Changing the discount priority") > **Tip:** If you cannot use drag-and-drop, expand the _Other actions_ menu by clicking the **Other actions** button (**...**) and then click either **Move up** or **Move down** to change the discount's priority. 3. (Optional) **Edit** () individual discounts and change the **Apply lower priority discounts** fieldas 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 new order. > **Note:** **Note** > > - The system does not stack Buy X Get Y discounts for individual units of products. If multiple Buy X Get Y discounts apply to a single product that is added multiple times to the shopping cart, the system applies the discounts according to their priority. Each application "uses up" the number of product units specified in the discount's "Buy" and "Get" conditions, and these units can no longer be processed by other Buy X Get Y discounts. > - If you have a discount for a group of products, and want to set a larger discount for a specific product from the same group, you need to create a new discount with the total discount amount and assign it a higher priority. > - Other [discounts](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts.md) of a different type (e.g., volume discounts, product coupons) are still applied regardless of the Buy X Get Y priority. ### Example – Buy X Get Y discount priority The following example sets a 10% discount on any book and an additional 5% discount to every bought _Steve Jobs (E-book_) product. 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. Create a new discount for the _Steve Jobs (E-book)_ product. - **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)_. 3. Drag the _Steve Jobs (E-book)_ discount using the **Move** () area above the _Buy a book, get 10% off_ discount in the listing. Now when a customer adds a book to the shopping cart, the discount for all books applies. If the _Steve Jobs (E-book)_ product is added to the shopping cart, the discount just for the book about Steve Jobs applies. ## Displaying Buy X Get Y discount data to customers To display information about applied Buy X Get Y discounts on your store's checkout pages, you need to correctly format the data of the items in the current shopping cart. ### In invoices and emails In [invoices](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-invoices.md) and [e-commerce notification templates](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-e-commerce-email-notifications.md), you can display Buy X Get Y discount data in the [transformation](https://docs.kentico.com/13/macro-expressions/writing-transformations-for-macros.md) applied to the **ContentTable** items (i.e. the product items in the related order). To show customers the price reduction granted by Buy X Get Y discounts for each item, display the **TotalDiscount** value of the transformed order item. The property contains the sum of the discount values for all Buy X Get Y discounts and [product coupons](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-product-coupons.md) applied to the given order item. ```xml title="Example - ContentTable item transformation" {% HTMLEncode(Localize(SKUName)) %} {% HTMLEncode(SKUNumber) %} {% Units %} {% HTMLEncode(UnitPrice.Format(Currency.CurrencyFormatString)) %} {% HTMLEncode(TotalDiscount.Format(Currency.CurrencyFormatString)) %} {% HTMLEncode(TotalPrice.Format(Currency.CurrencyFormatString)) %} ``` If you wish to include detailed information about the applied Buy X Get Y discounts, you need to process the data available in the **DiscountSummary** property of order items. _DiscountSummary_ is a collection of all Buy X Get Y discounts and product coupons that were applied to the given order item. Each record in the collection holds the following properties: - **Name** – the name of the discount as specified in the Buy X Get Y discounts application. - **Value** – the total amount saved after applying the discount to the given order item (for all product units). To format the _DiscountSummary,_ either [iterate through the collection](https://docs.kentico.com/13/macro-expressions/macro-syntax.md) and manually generate the output, or call the **ApplyTransformation** macro method and define a transformation for the summary items. ```csharp title="Example - Iterating through DiscountSummary" {% result = ""; if (DiscountSummary.Any()) { result += "";  } return result; %} ``` ## Reference | General | | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | The discount name that is displayed in the shopping cart, invoices, and emails. | | Code name | The unique identifier of the discount object (for example used by developers in custom 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 can be applied. If cleared, the discount is disabled. | | "Buy" Conditions | | | Buy any | Specifies the products that customers need to add to the shopping cart to obtain the discount.
**Products** – choose individual products.
**Products in sections** – choose entire sections of the [product tree structure](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-products/configuring-product-structure.md)
**Products in departments** – choose whole [departments](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/categorizing-products/departments.md) of products.
**Products with brands** – choose [brands](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-brands-and-manufacturers.md), which are assigned to products
**Products in collections** – choose product [collections](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-product-collections.md) (each product can be assigned to a collection)
For example, if you set the discount's **Minimum unit quantity** to 3 and choose 6 products in this field, the "Buy" conditions are fulfilled whenever a customer adds any combination of 3 products from the given set to the shopping cart.
Choose one of the options and then select the **Products**, **Sections**, **Departments**, **Brands** or **Collections** that fulfill the "Buy conditions". | | Exclude | You can optionally exclude products from the discount's "Buy conditions" (unless the _Buy any_ property is set to choose individual products). The exclusion options allow you to select [product sections](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-products/configuring-product-structure.md), [brands](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-brands-and-manufacturers.md) or [collections](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/managing-product-collections.md).
Choose the _products in sections_, _products with brands_ or _products in collections_ option in the **Exclude** property and then select the **Excluded sections**, **Excluded brands** or **Excluded collections**. | | 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 "Buy condition" products gets the discount.
**Specific product for discounted amount** – the system automatically adds a specific product to the 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 as a percentage or a fixed amount.
**Percentage** – the price of the cheapest unit or the product specified in **Get** is reduced by the specified percentage.
**Fixed amount** – the price of the cheapest unit or the product specified in **Get** is reduced by a specific amount in the site's [main currency](https://docs.kentico.com/13/e-commerce-features/configuring-on-line-stores/configuring-currencies.md). | | Amount | Specify the exact value of the discount. The amount must be a valid decimal number.
If the amount is a percentage, enter a number between 0 and 100.
If 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 does not add the product when:
you choose a product with [product options](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/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 are no available items left.**Info:** Customers cannot remove an automatically added product if they are entitled to it. If they try to remove the product, the system adds it again immediately. | | Coupons | | | Customer has to redeem a coupon to get the discount | If selected, only customers who enter a valid coupon code are able to apply the discount.
You can define coupon codes on the **Coupons** tab in the left menu. After enabling the field and saving the discount, you will be redirected there automatically.
See [Working with coupon codes](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-coupon-codes.md) to learn more.
**Examples**
The examples show how the auto-adding feature works if the discount is coupon-based.
**Example 1:**
The customer adds X to the cart, Y is not auto-added.
The customer enters a coupon code, Y is auto-added.
The customer removes the coupon code, Y is auto-removed.
**Example 2:**
The customer adds X to the cart, Y is not auto-added.
The customer adds Y.
The customer enters a coupon code, Y in the shopping cart is recalculated as free.
**Example 3:**
The customer enters a coupon code.
The customer adds X to the cart, Y is auto-added. | | Target customers | | | Available for | Determines which types of users are able to apply the discount:
**All visitors** – all customers are eligible for the discount.
**Registered users** – only [registered customers](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/customers.md) are eligible for the discount.
**Registered users in selected roles** – only registered customers in selected [roles](https://docs.kentico.com/13/managing-users/role-management.md) can use the discount. To specify the roles:
Click **Select roles** to open the **Select roles** dialog.
Choose 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 customers on the **Roles** tab. | | Discount processing | | | Apply lower priority discounts | If selected, other Buy X Get Y discounts with lower priority are applied to the order as well. If cleared, processing of Buy X Get Y discounts stops with this discount.
Note: The system does not stack Buy X Get Y discounts for individual units of products. If multiple Buy X Get Y discounts apply to a single product that is added multiple times to the shopping cart, the system applies the discounts according to their priority. Each application "uses up" the number of product units specified in the discount's "Buy" and "Get" conditions, and these units can no longer be processed by other Buy X Get Y discounts. | | Limit use per order | Determines how many times the system can apply the discount to a single order. If you leave the value empty, the number of discount applications is unlimited.
For example, if a discount has the **Minimum unit quantity** set to 2 and a **100% discount** on the **cheapest** product:
A customer adds 3 products to their shopping cart.
In the shopping cart, the system applies a 100% discount to the cheapest product.
If the customer adds another 3 products, the cart contains 6 total products. If **Limit user per order** is not set, the system applies the discount twice, so the two cheapest products are for free. If **Limit user per order** is set to 1, the system applies the discount only once, so only the first cheapest product is for free. | | Valid to | Specifies the time and date until which the discount is valid. If you leave the value empty, the discount is valid permanently (starting from the **Valid from** date). | | Valid from | Specifies the time and date from which the discount is valid. If you leave the value empty, the discount applies at any time before the **Valid to** date. | ## Buy X Get Y discount API Buy X Get Y discounts are called MultiBuyDiscounts in the API. The basic API consists of the following classes: - **MultiBuyDiscountInfo** – each object represents a Buy X Get Y discount (or [product coupon](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/discounts/working-with-product-coupons.md)). - **IMultiBuyDiscountInfoProvider** – service that provides basic management functionality for Buy X Get Y discounts (and product coupons). The system applies Buy X Get Y discounts on the level of individual items in the shopping cart (each item can contain multiple units of the same product). In the API and macros, you can access related values using the following: - **ShoppingCartInfo.CartItems** (**ShoppingCartItems** in macros) – a collection of all **ShoppingCartItemInfo** objects within a given shopping cart object. - **ShoppingCartItemInfo.TotalDiscount** –decimal value containing the sum of all price reductions granted by Buy X Get Y discounts and product coupons applied to the given shopping cart item. - **ShoppingCartItemInfo.DiscountSummary** – a collection of **SummaryItem** objects applied to the given shopping cart item. The collection contains both Buy X Get Y discounts and product coupons that apply to the shopping cart item. - **SummaryItem** – a simplified data view used to summarize applied discounts. Contains only the _Name_ and _Value_ of the discount.