A Selectable Gift With Purchase (GWP) widget lets you present multiple free gift options and allow the customer to choose one gift from the selection, rather than having a gift added to their cart automatically. This guide walks you through how to create and configure a Selectable Gift With Purchase widget using Rebuy's Smart Cart.
Selectable GWP widgets are built by customizing a cross-sell widget with advanced code and conditional rules. Because this setup requires custom code, it is recommended for advanced users who are comfortable working with Rebuy's widget Advanced tab and CSS settings.
Note: A Selectable Gift With Purchase widget requires Rebuy's Smart Cart. This widget type is not supported outside of the Smart Cart.
There are two display styles for Selectable GWP widgets:
Pop-up: The gift selection appears as a popup overlay triggered by a cart action (such as adding an item to the cart). The customer selects a gift from the popup, and it is added to the Smart Cart.
Embedded: The gift selection appears directly inside the Smart Cart drawer as an inline widget. The customer selects a gift from within the cart itself.
Both styles use the same underlying widget configuration, with differences in the display settings and the custom code applied in the Advanced tab.
Choosing the Right Gift With Purchase Approach
Before setting up a Selectable Gift With Purchase widget, determine which Rebuy gift approach best fits your promotion. Rebuy offers several ways to add a free gift to a customer's order, depending on how many products you are offering and whether the customer needs to make a selection.
Scenario | Recommended approach |
One gift product, no variant selection needed | |
One gift product, customer must choose a variant (size, color, etc.) | |
Multiple gift products to choose from, customer selects one | Selectable Gift With Purchase widget (this guide) |
Important: "Selectable Gift With Purchase" is not a standard Rebuy widget type. It is a customized cart cross-sell widget that requires manual code configuration. Only follow this guide if you want to present multiple gift product options and let the customer select one gift from those options.
Setting Up a Selectable Gift With Purchase Widget
The following steps walk you through the full setup for a Selectable Gift With Purchase widget. These steps apply to both the pop-up and embedded display styles. After completing this setup, follow the display-specific instructions in the section for your chosen style (pop-up or embedded).
Step 1: Create a Cross-Sell Widget in Smart Cart
To create a Selectable Gift With Purchase widget, you start by adding a cross-sell widget component to your Rebuy Smart Cart.
Navigate to the Rebuy Dashboard and open the Smart Cart editor you want to add the widget to.
Click "Add +" in the Cross-Sells Component within the Smart Cart editor.
Select Cross-Sell Widget from the component list and create a new Widget.
Once the cross-sell widget is created, click on the widget name or the settings icon to open its configuration editor.
Step 2: Enable the Discount Using Shopify Functions
To ensure that the free gift product displays as Free in the widget, the Smart Cart, and at checkout, you need to enable the discount setting in the widget's configuration. Rebuy uses Shopify Functions to create an automatic discount that applies to the gift product when a customer selects it.
In the widget's editor, locate the Discount tab.
Select Discount Type "Percentage"
Toggle ON the discount setting "Discounted By Functions". This creates an Automatic Discount in Shopify scoped to widget and the discount will be automatically applied to the applicable items when a customer adds them from the widget.
Configure the discount to apply a 100% discount to the gift products.
Shopify Functions for discounting is available for all Shopify plan types. For more information on how discounting works with Shopify Functions in Rebuy, see the Rebuy Discounting Overview.
Note: If you prefer to create and manage your own discount setup directly in Shopify instead of having Rebuy create the discount automatically, toggle off the Shopify Functions setting. Rebuy will still display the product as free in the widget, but you will be responsible for configuring a matching discount in Shopify to ensure the gift is actually discounted at checkout.
Important: Avoid using a $0-priced product as your gift. Instead, give the product a real price and let the Use Shopify Functions setting discount it to $0 for qualifying customers. A $0 product can cause exploits because any customer who finds the product URL can add it to their cart for free — without qualifying for the promotion. Giving the gift a real price and using Shopify Functions to discount it to $0 only for qualifying customers prevents this.
Step 3: Configure Data Source Rules
The Data Source rules determine when the Selectable Gift With Purchase widget appears to the customer. These rules define the conditions a customer's cart must meet before the gift offer is triggered.
Open the Data Source tab in the widget's settings.
Leave the Filter input products checkbox unchecked.
Add a rule that matches your promotion's conditions.
The most common rule is a cart subtotal threshold (for example, "Show this widget when the cart subtotal is $249.99 or more"). Other conditions you can use include rules based on specific products in the cart, cart item count, customer tags, or any other supported Rebuy rule.
Important: Leave the Filter input products checkbox unchecked for Selectable GWP widgets. Because this is a Cart Cross-Sell widget, its Data Source uses the items currently in the cart as input products. If Filter input products is enabled, the Data Source will filter out any gift products if they had already been added to the cart, which can cause the widget to return no products and break the selection flow. The custom JavaScript code added in a later step already handles hiding the widget after a gift is selected — the Data Source filter should not duplicate that logic.
For a full overview of how Data Sources work, see Data Sources 101. For cart-specific rule options, see Data Sources and the Cart.
Step 4: Choose Your Display Style (Embedded or Pop-Up)
After completing Steps 1 through 3, choose how the Selectable Gift With Purchase widget will appear to your customers. There are two display styles, and each requires its own configuration in the widget settings and custom code in the Advanced tab.
Embedded — The gift selection appears directly inside the Smart Cart drawer as an inline widget. Follow the instructions in How to Create an Embedded Selectable Gift With Purchase Widget.
Pop-up — The gift selection appears as a popup overlay triggered by a cart action. Follow the instructions in How to Create a Pop-Up Selectable Gift With Purchase Widget.
How to Create an Embedded Selectable Gift With Purchase Widget
An embedded Selectable Gift With Purchase widget displays the gift selection directly inside the Smart Cart drawer as an inline component. Instead of a popup overlay, the gift options appear within the cart itself, and the widget hides after the customer selects a gift.
Add the Embedded Custom Code
The embedded Selectable Gift With Purchase widget requires custom JavaScript code to control when the widget is visible inside the Smart Cart. This code checks whether the customer has already selected a gift, hides the widget when a gift is in the cart, and removes the gift if the Data Source conditions are no longer met.
In the widget's editor, open the Advanced tab.
Copy the following code and paste it into the Ready section of the Advanced tab:
function embedSelectableGWP () {
setTimeout(() => {
//check for a free gift item in the cart
const giftItem = Rebuy.SmartCart.items().find(item => item.properties?._widget_id === `${widget.id}`);
//hide widget if there is a gift item
if (giftItem) {
document.querySelector(`#rebuy-widget-${widget.id}`).style.display = 'none';
//display the widget if not
} else {
document.querySelector(`#rebuy-widget-${widget.id}`).style.display = 'block';
}
//if widget rules is no longer match, remove free gift
if (widget.data?.metadata.matched_rules.length === 0) {
Rebuy.Cart.removeItem(giftItem)
}
}, 500)
}
//runs on page load
embedSelectableGWP()
//runs on each cart change
document.addEventListener('rebuy:cart.change', embedSelectableGWP)
This code does three things:
Checks for an existing gift. It looks through the Smart Cart line items to find any product that was added by this specific widget (identified by the widget ID).
Shows or hides the widget. If no gift from this widget is in the cart and the Data Source rules are currently matched, the widget is displayed inside the Smart Cart. If a gift has already been selected, the widget is hidden using
display: noneso the customer only sees the gift as a regular line item in the cart.Removes the gift if conditions change. If the customer modifies their cart so the Data Source rules are no longer met, the gift is automatically removed from the cart.
The code runs once on page load and then again every time the cart changes, using the rebuy:cart.change event listener.
Embedded Selectable GWP: See It in Action
To see an embedded Selectable Gift With Purchase widget in action, watch the video walkthrough linked below. The video demonstrates a customer opening the Smart Cart, seeing the gift selection widget inline within the cart, choosing a free gift, and the widget hiding once the gift is added.
How to Create a Pop-Up Selectable Gift With Purchase Widget
A pop-up Selectable Gift With Purchase widget displays the gift selection as a popup overlay that appears on top of the Smart Cart. The popup is triggered by a cart action (typically when a customer adds an item to the cart) and prompts the customer to choose a free gift before continuing.
Set the Display Type to Pop-Up
Configure the widget to display as a popup instead of an inline embed within the Smart Cart.
In the widget's settings panel, expand the Widget Settings tab.
Under Display Type, select Popup.
Add the Pop-Up Custom Code
The pop-up Selectable Gift With Purchase widget requires custom JavaScript code to control when the popup appears and when it is hidden. This code checks whether the customer has already selected a gift, shows the popup when the Data Source conditions are met, and removes the gift from the cart if the conditions are no longer met.
In the widget's settings panel, expand the Advanced tab.
Copy the following code and paste it into the Ready section of the Advanced tab:
function popupSelectableGWP() {
setTimeout(() => {
//check for free gift items in the cart
const giftItem = Rebuy.SmartCart.items().find((item) => item.properties._widget_id === `${widget.id}`);
//if there is no gift item and the widget rules match
if (!giftItem && widget.data.metadata.matched_rules.length) {
widget.show();
//hide the widget if theres already a gift in cart
} else {
widget.hide();
}
//if widget rules is no longer match, remove free gift
if (widget.data?.metadata.matched_rules.length === 0) {
Rebuy.Cart.removeItem(giftItem);
}
}, 300);
}
popupSelectableGWP(); //runs on page load
document.addEventListener("rebuy:cart.change", popupSelectableGWP); //runs on cart change
This code does three things:
Checks for an existing gift. It looks through the Smart Cart line items to find any product that was added by this specific widget (identified by the widget ID).
Shows or hides the popup. If no gift from this widget is in the cart and the Data Source rules are currently matched, the popup is displayed. If a gift has already been selected, the popup stays hidden.
Removes the gift if conditions change. If the customer modifies their cart so the Data Source rules are no longer met (for example, they remove items and the subtotal drops below the threshold), the gift is automatically removed from the cart.
The code runs once on page load and then again every time the cart changes, using the rebuy:cart.change event listener.
Pop-Up Selectable GWP: See It in Action
To see a pop-up Selectable Gift With Purchase widget in action, watch the video walkthrough linked below. The video demonstrates a customer adding items to the cart, triggering the gift selection popup, choosing a free gift, and seeing it added to the Smart Cart with the discount applied.
Optional: Customizing the Gift Line Item in Smart Cart
After setting up your Selectable Gift With Purchase widget, you may want to adjust how the gift line item appears inside the Smart Cart. The following optional steps use CSS to hide default Smart Cart elements on the gift line item or to prevent customers from clicking through to the gift product's page.
Hide the Quantity Selector and Subscription Option on the Gift Line Item
By default, Smart Cart line items display a quantity selector and a subscription upgrade option. To prevent customers from changing the quantity of the free gift or being prompted to subscribe, add CSS code to hide these elements on any line item added by the GWP widget.
Add the following CSS to your Rebuy Theme by navigating to Settings > Themes in the Rebuy Dashboard and pasting the code into the CSS input:
.property-value-XXXXX .rebuy-cart__flyout-item-quantity-widget {
display: none;
}
.property-value-XXXXX .rebuy-cart__flyout-item-subscription {
display: none;
}
Important: Replace XXXXX with your widget's actual ID number. You can find the widget ID in the widget's settings panel or in the URL when editing the widget.
Disable Product Page Links on the Gift Line Item
This step is only necessary if the free gift products you are offering are hidden from all other areas of your online store and you do not want customers to be able to click through to those product pages from within the Smart Cart.
To remove the clickable link on the gift line item's product title and image in the Smart Cart, add the following CSS to Smart Cart > Custom CSS:
/* Replace XXXXX with the widget's ID */
.rebuy-cart__flyout-item.property-value-XXXXX .rebuy-cart__flyout-item-product-title,
.rebuy-cart__flyout-item.property-value-XXXXX .rebuy-cart__flyout-item-media {
pointer-events: none;
}
Important: Replace XXXXX with your widget's actual ID number.
Optional: Pairing with the Tiered Progress Bar using the Decorative Tier
A Selectable Gift With Purchase widget can be paired with a Decorative Tier in Rebuy's Tiered Progress Bar to give customers a visual progress milestone toward their gift selection. The Decorative Tier handles the progress bar display — showing customers how close they are to the threshold — while the Selectable GWP widget handles the gift selection experience when they get there.
The Decorative Tier is a display-only tier type in the Tiered Progress Bar. It does not automatically add a gift or apply a discount on its own. When paired with a Selectable GWP widget, the Decorative Tier shows the cart milestone and the widget triggers the gift selection popup or embedded offer when the customer's cart meets your Data Source Rules.
The screenshot below shows an example of a Tiered Progress Bar Decorative Tier paired with a Selectable Gift With Purchase widget for customer-choice gift rewards.
How to pair the Selectable GWP Widget with the Tiered Progress Bar Decorative Tier
To pair a Selectable GWP widget with a Tiered Progress Bar Decorative Tier:
Set up your Selectable GWP widget using the steps in this guide.
In your widget's Data Source Rules, add a Cart Subtotal rule set to "Is Greater Than" and enter an amount just below your intended threshold (for example, if your threshold is $100, set the rule to
$99).In your Smart Cart editor, open the Tiered Progress Bar component and add a new tier.
Set the tier type to Decorative-Only.
Set the Unlock Price to your threshold amount (for example,
$100).Add a Decorative Tier Label that describes the reward (for example, "Choose Your Free Gift").
Save your changes.
Important: The Cart Subtotal rule uses "Is Greater Than," so set your rule value $1 below your Decorative Tier's Unlock Price. For example, if your Unlock Price is $100, set the rule to "Cart Subtotal Is Greater Than $99." This ensures the progress bar milestone and the Selectable GWP widget both trigger at the same cart value.
For full instructions on setting up the Decorative Tier — including label copy, icon configuration, and the full setup walkthrough — see Using the Decorative Tier in Rebuy's Tiered Progress Bar.
Frequently Asked Questions About Selectable Gift With Purchase
Can I use a Selectable Gift With Purchase widget for a "Buy X, Get One Free" (BOGO) promotion?
Yes, but only when the qualifying product and the gift product are different items (Buy X, Get Y). For example, you can set a Data Source rule like "IF Cart Contains [Product A], RETURN [Product B]" and the widget will work as expected. The discount setting using Shopify Functions will ensure the selected gift is discounted to free at checkout.
Important: Buy X, Get X (same product) is not supported. The Selectable GWP widget cannot handle a true Buy X, Get X offer where the qualifying product and the gift product are the same item. This creates an infinite loop: the widget automatically adds the gift to the cart, but because the gift is the same product as the qualifying item, the widget treats it as another qualifying purchase. If the customer removes the free item, the widget adds it back, and the cycle repeats.
For example, a "Buy 1 red candle, Get 1 red candle free" promotion would loop — the customer removes the free candle, and the widget immediately adds it back.
Can a customer select more than one free gift from a Selectable Gift With Purchase widget?
By default, the custom code for a Selectable Gift With Purchase widget allows the customer to select only one gift. Once a gift is added to the cart, the widget (either the popup or the embedded version) hides so the customer cannot add a second gift from the same widget. If you need to allow multiple gift selections, you would need to modify the custom code in the Advanced tab to accommodate that behavior.
What happens if the customer removes items from their cart and no longer qualifies for the free gift?
If a customer modifies their cart so that the Data Source rules for the Selectable Gift With Purchase widget are no longer met, the custom code automatically removes the free gift from the cart. For example, if the promotion requires a $50 cart subtotal and the customer removes items so the subtotal drops below $50, the gift is removed on the next cart change event.
What happens if a customer removes items at checkout and drops below the qualifying threshold?
The Selectable Gift With Purchase widget is a cart-based cross-sell widget and does not run checkout validation logic. If a customer removes items at checkout and their subtotal drops below the qualifying threshold, the discount on the gift will be removed at checkout, but the gift product itself will remain in the order. The customer would need to return to the storefront and manually remove the gift from their cart.
Can I use a different discount method instead of Shopify Functions?
Rebuy's recommended approach for discounting Selectable Gift With Purchase products is Shopify Functions, which is available on all Shopify plan types. If you toggle off the Shopify Functions setting in the widget, Rebuy will display a visual discount in the widget (showing the product as free), but the full price will be charged at checkout. For more details on discount options, see the Rebuy Discounting Overview.
Does the Selectable Gift With Purchase widget work without Rebuy's Smart Cart?
No, the Selectable Gift With Purchase widget requires Rebuy's Smart Cart. The custom JavaScript code used to control the widget's visibility and to detect gift line items relies on Smart Cart's API (Rebuy.SmartCart.items() and Rebuy.Cart.removeItem()). This widget cannot be used with Shopify's native cart or other third-party cart solutions.
How do I find my widget ID to use in the CSS code?
Your Rebuy widget ID is a numeric identifier assigned to each widget. You can find it in two places: in the widget's settings panel at the top of the page, or in the browser's URL bar when you are editing the widget (it appears as a number in the URL path). Use this ID to replace XXXXX in the CSS code snippets provided in this guide.
Troubleshooting Selectable Gift With Purchase Widgets
The pop-up is not appearing when items are added to the cart
If the Selectable Gift With Purchase popup is not appearing when a customer adds items to the cart, check the following:
Data Source rules: Verify that the Data Source conditions are being met. Open the widget's Data Source tab and confirm the rules match the current cart state (for example, the cart subtotal meets the threshold).
Display Type: Confirm the widget's Display Type is set to Popup and the trigger is set to Add to cart in the Widget Settings tab.
Advanced code: Make sure the custom JavaScript code is pasted into the Ready section of the Advanced tab (not the CSS or HTML sections). Check for any JavaScript errors in the browser console.
Existing gift in cart: The code intentionally hides the popup if a gift from this widget is already in the cart. If you are testing, clear the cart completely and try again.
The free gift is not being removed when the customer no longer qualifies
If the free gift stays in the cart after the customer's cart no longer meets the Data Source conditions, confirm that the custom code in the Advanced tab includes the rule-matching check. The relevant code block checks widget.data?.metadata.matched_rules.length === 0 and calls Rebuy.Cart.removeItem(giftItem). If this check is missing or modified, the automatic removal will not work.
Also verify that the rebuy:cart.change event listener is included at the bottom of the code. Without this listener, the code only runs on page load and will not react to subsequent cart changes.
If the free gift stays in the cart at Checkout after the subtotal drops below the qualifying threshold, this is expected behavior at checkout — the Selectable Gift With Purchase widget is cart-based and does not run validation logic at checkout. The discount on the gift will be removed, but the gift product itself will not be automatically removed. The customer would need to return to the storefront to remove it manually.
The gift product is not showing as free at checkout
If the gift product displays as free in the Rebuy widget and Smart Cart but is charged at full price during checkout, check the following:
Shopify Functions toggle: In the widget's settings, confirm that the Shopify Functions discount toggle is enabled. If this toggle is off, Rebuy only applies a visual discount in the widget — the actual price is not discounted at checkout.
Discount conflicts: Check whether any other Shopify discount codes or automatic discounts are conflicting with the Rebuy Shopify Functions discount. Shopify limits the number of automatic discounts that can be combined.
Cart subtotal dropped below the threshold at checkout: The Selectable Gift With Purchase widget does not run checkout validation logic. If the cart subtotal drops below the qualifying threshold at checkout — from removing items, applying a discount code, or any other cart change — the discount on the gift will be removed but the gift product itself will remain. The customer would need to return to the storefront to remove it manually.
For more details, see the Rebuy Discounting Overview.