> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.hoppyapps.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 🚀 How to setup Buy X Get Y

Want to reward customers with a **different product** when they buy enough of something? 🎁

That’s exactly what the **Buy X Get Y** offer in Hoppy Bundles is designed for.

With this offer type, you can create conditional deals such as:

* 🛒 Buy 2 T-Shirts → Get a Cap at 50% OFF  
* 💸 Buy 3 Sneakers → Get a pair of Socks FREE  
* 🎁 Buy 2 Coffee Beans → Get a Mug at a discount

—and display them as neat, clickable tiers directly on your product page.

Customers simply pick the deal they like, add it to the cart, and the discount on the “Y” product is applied automatically at checkout ✨

---

# **📍 Where the Buy X Get Y Widget Appears**

The Buy X Get Y widget appears on your **Product Page**, right below the Add to Cart button (default placement).

You can also place it anywhere else on the product page using the **Custom placement** option (covered later in this guide).

ℹ️ Buy X Get Y uses the same setup screen as **Quantity Break** — it just opens pre-filled with Buy X Get Y tiers, the violet **YAY\! It’s BOGO** theme, and a “Buy X Get Y” block title. This guide focuses only on what’s different for Buy X Get Y; shared settings are summarized briefly.

---

# **🛠️ Example Setup Used in This Documentation**

In this documentation, we’ll configure the following tier structure:

* 🛒 1 Pair → Standard Price (No Discount)  
* 🎁 Buy 2 → Get 3 of another product at a discount  
* 🎁 Buy 3 → Get 4 of another product at a discount

These are exactly the tiers the app pre-fills for you when you start a Buy X Get Y offer — you can edit every part of them ⚙️

---

# **✅ Before You Begin — Enable the App Embed**

For the Buy X Get Y widget to appear on your storefront, the app embed must be enabled inside your Shopify theme.

Go to:

**Shopify Admin → Sales Channels → Online Store → Themes → Customize → App Embeds**

Then:

* Find **Bundles App Embed**  
* Toggle it ON  
* Click Save

⚠️ **Important**: Without the app embed enabled, your published offer will not be visible on the storefront — even if everything inside the app is configured correctly.

---

# **🎯 Step 1 — Create a New Buy X Get Y Offer**

Open the **Hoppy Bundles** app from your Shopify Admin.

Then:

→ Click **Create New Offer** to open the offer type selection page.

→ Find the **Buy X Get Y (Conditional Offer)** card — *“Buy a specific quantity and get another product at a discount”* — and click **Create Buy X Get Y**.

The setup page opens with everything pre-filled for a Buy X Get Y deal:

* 🎨 Template → **YAY\! It’s BOGO** (violet theme)  
* 📰 Block title → **Buy X Get Y**  
* 🎁 Tiers → **Buy X Get Y Free** discount type with Buy / Get conditions ready to edit

💡 Starting from this card saves you from building the tiers manually — but you can still change the template and every tier afterwards.

---

# **🧩 Step 2 — Name Your Offer & Choose Where It Applies**

The first screen asks for the basics before anything else.

---

## **🏷️ Offer Name**

This field is used for internal purposes only.

Customers will never see this name.

You can use any recognizable name such as:

* Buy 2 Get a Cap  
* Sneaker \+ Socks Deal  
* Black Friday BXGY

💡 Using proper internal naming makes it easier to identify setups later, especially if your store runs multiple offers.

---

## **📦 Apply Offer On**

This setting controls which products act as the **“X” products** — the ones customers must buy to unlock the deal.

There are 3 available options:

* **All Products** → the offer applies to every product in your store  
* **Product** → the offer applies only to the products you select  
* **Collection** → the offer applies to every product inside the collections you select

If you choose **Product** or **Collection**, a **Select Product** / **Select Collection** button appears. Click it to open your Shopify resource picker and choose one or more items.

⚠️ **Important**:

* Switching between **All Products**, **Product**, and **Collection** clears your current selection — pick the right mode first, then select your items.  
* Only **one published offer is allowed per product or collection**. If another published offer already covers the same product, you won’t be able to publish this one until the existing offer is converted back to a draft.

---

# **🎨 Step 3 — Confirm Your Template**

Scroll down to the **Select Your Preferred Offer** section.

For Buy X Get Y, the **YAY\! It’s BOGO** template (violet, deal-themed) is already selected for you — it matches this offer type perfectly.

You can still swipe through and pick a different look if you prefer:

* **Build one from scratch** → start with a clean, minimal layout  
* **Bundle & Save** → the classic green multi-tier look  
* **Limited Time Offer** → orange, urgency-themed  
* **Flash Sale Madness\!** → pink, sale-themed

Click **Apply selected template** to continue.

ℹ️ The **Apply selected template** button stays disabled until you’ve selected at least one product or collection (when using the **Product** or **Collection** mode).

Once applied, the full setup editor opens — with a live preview of your widget on the right side of the screen 👀

---

# **⚙️ Step 4 — Configure Your Buy X Get Y Tiers (General Tab)**

This is the heart of the setup ❤️

Each deal lives on its own tab (**Offer 1**, **Offer 2**, **Offer 3**…). Click a tab to edit that tier.

The pre-filled setup looks like this:

* **Offer 1** → Quantity `1`, Discount type `No Discount` (a standard-price baseline tier)  
* **Offer 2** → Discount type `Buy X Get Y Free`, Buy `2`, Get `3`, tagged **Most Popular**  
* **Offer 3** → Discount type `Buy X Get Y Free`, Buy `3`, Get `4`

Let’s go through the fields that make a Buy X Get Y tier work.

---

## **💸 Discount Type → Buy X Get Y Free**

Set the tier’s **Discount type** dropdown to **Buy X Get Y Free**.

Once selected, the regular **Discount** value field is replaced by two condition fields:

* **Buy** → how many items of the “X” product the customer must buy. This field is **locked** — it always follows the tier’s **Quantity** value.  
* **Get** → how many units of the “Y” product the customer receives. This field is **editable** — set it to whatever your deal promises.

### **Example**

* Buy `2` \+ Get `1` → “Buy 2, Get 1”  
* Buy `3` \+ Get `2` → “Buy 3, Get 2”

⚠️ **Please note**: Switching a tier’s discount type **to** `Buy X Get Y Free` resets the **Get** value to `1` and clears the selected Y product — so pick the discount type first, then configure the rest.

ℹ️ If you want customers to get more of the **same** product free instead of a different product, use the **BOGO (Buy One Get One)** discount type instead — see the dedicated BOGO guide.

---

## **🎁 Get Product — Select Y Product**

ℹ️ This section only appears when the discount type is **Buy X Get Y Free**.

This is where you choose the **“Y” product** — the product the customer gets at a discount when they buy enough of the “X” product.

→ Click **Select Y Product** to open your Shopify resource picker and choose a single product.

Once selected, the product appears inside the tier with its image and title. Until then, you’ll see **“No product selected”**.

⚠️ **Important**: Don’t skip this step — without a Y product selected, the tier has nothing to give away. Always double-check each Buy X Get Y tier has its own Y product before publishing.

💡 You can use a **different Y product per tier** — for example, a small freebie on the “Buy 2” tier and a premium one on the “Buy 3” tier.

---

## **🔢 Quantity**

The number of “X” items the customer must buy to unlock this tier.

For Buy X Get Y tiers, the **Buy** condition automatically follows this quantity — change the quantity and the Buy value updates with it.

⚠️ Quantity must be greater than 0 — you’ll see an inline error if it isn’t.

---

## **🏷️ Offer Title, Discount Label & Tag**

Each tier has three text elements you can customize:

* **Offer Title** → the main text on the tier, e.g. “Buy 2 Get 3”  
* **Discount Label** → the deal text shown on the tier, e.g. “Buy 2 Get 3 at 50% OFF”  
* **Tag** → a small badge, e.g. “Most Popular”

The **Discount Label** and **Tag** fields each have an **eye icon** 👁️ on the right side — click it to show or hide that element on the storefront.

💡 The pre-filled tiers already come with “Buy 2 Get 3” style titles and labels — just tweak the wording to match your actual deal, so customers aren’t confused about what they’re getting.

---

## **➕ Add / 🗑️ Delete Tiers**

Below the offer tabs you’ll find:

* **Add Offer** → adds a new tier tab (maximum **6 tiers**). New tiers start as a plain `No Discount` tier — switch the discount type to **Buy X Get Y Free** and configure the Buy / Get / Y product yourself.  
* **Delete** → removes the currently selected tier (minimum **2 tiers** required)

If you hit one of these limits, a small toast message will let you know.

---

## **📰 Block Title & Footer Text**

These control the text above and below the widget:

* **Block Title** → pre-filled with “Buy X Get Y” — change it to something punchier like “Bundle & Save” or “Buy More, Get More 🎁”  
* **Footer Text** → e.g. “Free Shipping”

Both fields come with an **eye icon** to hide them completely if you prefer a cleaner look.

---

# **🛠️ Step 5 — Configure Settings**

Scroll down to the **Settings** card. These checkboxes work exactly like they do for Quantity Break offers — here’s the quick version:

**👀 Appearance and Looks**

* **Show unit price** / **Show total price** → display per-unit and per-tier prices inside the offer  
* **Hide header and footer lines** → cleaner widget without the divider lines  
* **Use custom text for Out of Stock** → show your own message when a product is out of stock (enabling it reveals a text field)

**⚙️ Functionality**

* **Let customers choose different variants for each item** → customers can pick a different variant for every unit in the tier  
* **Display widget below add to cart button** → renders the widget directly below your Add to Cart button  
* **Skip cart directly to checkout** → customers go straight to checkout after adding a tier  
* **Show compare to price** → displays the strikethrough compare-at price (enabling it reveals **Custom compare price** and a read-only **Shopify product compare price** field)

**🔄 Enable Discount Combination**

* **Order discounts** / **Shipping discounts** → let this offer’s discount combine with order-level and shipping discounts at checkout

ℹ️ Product discount combination is always on. Due to Shopify restrictions, this setting applies globally to all new offers of this type.

Below Settings you’ll also find **Multiple Markets** (market-specific pricing) and **Translation** (translate widget texts). Both are optional and covered in their own dedicated guides.

---

# **🎯 Step 6 — Targeting & Placement (Optional)**

Switch to the **Targeting & Placement** tab to control where the widget appears and who sees it.

* **Placement** → **Below Add to Cart Button (Default)** is recommended for most stores. Choose **Custom (only on product page)** if you want to position the widget yourself — after saving, the app gives you a **Hoppy bundles ID** and a **code snippet** you can place anywhere in your theme.  
* **Customer Targeting** → show the offer only to logged-in customers, or show/hide it based on customer tags and lifetime spent  
* **Geolocation Targeting** → limit the offer to specific countries (default: all locations)  
* **Scheduling** → set a **start** and **end** date/time for the offer — handy for flash sales ⏰

ℹ️ All of these are optional. If you skip them, the offer simply shows to everyone, everywhere, right away. Advanced targeting is covered in detail in its own dedicated guide.

---

# **🎨 Design Tab (Optional)**

The **Design** tab controls the visual styling of the widget — fonts, text sizes, colors, variant selector sizing, and border width/radius.

💡 Every change reflects instantly in the live preview on the right — both in the **desktop** and **mobile** preview panels.

ℹ️ The violet BOGO theme already looks great out of the box, so this step is entirely optional. Styling is covered in depth in the dedicated design guide.

---

# **⚠️ Important Notes Before You Publish**

* 🎁 Every **Buy X Get Y Free** tier needs its own **Y product** selected via **Select Y Product** — a tier without one has nothing to give.  
* 🔒 The **Buy** value is locked to the tier’s **Quantity** — edit the quantity if you need a different Buy condition.  
* 🔁 Switching a tier to **Buy X Get Y Free** resets **Get** to `1` and clears the Y product — set the discount type first.  
* ✏️ Keep **Offer Title** and **Discount Label** in sync with your actual Buy / Get numbers, so the widget never promises something different from what the discount delivers.  
* 1️⃣ Only **one published offer** is allowed per product or collection.

---

# **✅ Final Step — Save & Publish**

Once everything looks good in the preview:

1. Click **Save** in the save bar at the top of the page  
2. Click **Publish** to make the offer live ⚠️ **Please note**:  
* The **Publish** button is disabled while the offer is brand new — **save first**, then publish.  
* Publishing creates an **automatic discount** in your **Shopify Admin → Discounts**. This is what actually applies the Y product discount at checkout — please don’t delete or edit it manually.  
* If the app embed is not enabled in your theme, a banner will appear after saving with an **Enable App Embed** shortcut button — click it, toggle the embed on, and save your theme.  
* If publishing fails because another published offer already covers the same product or collection, convert that existing offer to a draft first, then publish again.

Your Buy X Get Y offer is now live 🚀

---

# **🎉 Final Result**

Once configured successfully:

✅ Customers see your Buy X Get Y tiers directly on the product page ✅ Buying the required quantity unlocks the discounted “Y” product automatically ✅ The discount applies at checkout — no coupon codes needed ✅ Tiers, tags, and labels update instantly from the app

Here’s how the finished widget looks on the storefront — clear deals, a highlighted best-value tier, and one-click selection ✨

---