How offer tiers work

Every bundle in Bundlex is built from a set of offers, also called tiers. An offer is a single rung on a quantity ladder, for example "Buy 1", "Buy 2", or "Buy 3", and each rung carries its own quantity, discount, and widget text. This article explains how that model works, how the default tier and ordering behave, and how the customer's choice carries through to checkout.

What an offer is

A bundle holds an ordered list of offers. A bundle can have up to 10 offers. Each offer is configured independently and has three core parts:

• Quantity threshold - the number of units this tier applies to (for example 1, 2, or 3).
• Discount - the discount type plus its amount. Types include Percentage, Discount per item (fixed), Exact amount, Buy X Get Y, Free gift, or None.
• Widget text - the title, subtitle, badge, and label shown for that tier in the product-page widget. Titles and subtitles can use template variables like {{saved_percentage}}.

Offers can also carry free gifts and paid cross-sells ("extras") and benefit bullets, but the quantity, discount, and text are what define the tier itself.

The pre-selected (default) tier

Exactly one offer in a bundle is the default (pre-selected) tier. This is the offer that appears already selected when a shopper lands on the product page. You choose it from the Pre-selected offer dropdown in the widget settings, which lists every offer in the bundle.

A bundle always has a default. If no offer is explicitly marked as default, Bundlex falls back to the first offer in the list. Many merchants set the default to the tier they most want to promote, often a middle or higher-quantity rung where the savings look most attractive.

Ordering and reordering

Offers display in the widget in the order they appear in the bundle editor, top to bottom. Each offer has a Move up and Move down control so you can rearrange the ladder, for example to put your "best value" tier in the middle. You can also duplicate an offer (the copy is inserted right after the original and is never marked as default) or delete one.

Order is purely about how the ladder is presented. It does not have to match ascending quantity, though listing tiers from lowest to highest quantity is the most common and clearest layout.

Two offers can share the same quantity threshold (for example "Buy 1" and "Buy 1 + gift"). Bundlex keeps them distinct by their position in the offer list, so both can coexist in the same bundle.

How the chosen tier reaches checkout

When a shopper picks a tier and adds to cart, the widget writes a hidden _bundlex property onto the cart line. Among other tracking data, that property records which offer the customer chose (its index in the bundle). At checkout, Bundlex's cart discount (a Shopify Function) reads this tag and applies the matching offer's discount to that line. The same tag is also used for revenue attribution.

This tagging is how the discount the shopper saw on the product page becomes the discount they actually get at checkout. The _bundlex property is hidden from customers and cannot be removed from the admin.

For straightforward volume tiers (no paid cross-sells), the cart discount can still adjust to the cart's real quantity. If the customer drops below the tagged tier's quantity, it steps them down to the matching rung. If a different volume tier would give them a better deal at the cart's quantity, it can promote them to that tier. Tiers that include paid cross-sells (true bundles) are treated as a fixed commitment and are applied only when the customer explicitly selected them. See Display as bundle for how cross-sells turn an offer into a set.

The storefront requires an exact quantity match

This is the most important behavior to understand about the widget. On the product page, a tier only activates when the cart quantity exactly matches that tier's quantity threshold.

If a shopper changes the quantity selector to a number that matches a tier, the widget selects that tier. If they change it to a number that does not match any tier, the widget deselects all tiers and hides the totals section until the quantity lines up with a tier again.

Practical consequences:

• If you want the discount to feel "always on" as quantity grows, build a tier for each quantity you expect shoppers to buy. Gaps in the ladder leave those in-between quantities with no selected tier on the widget.
• The exact-match rule is a storefront widget behavior. The checkout-time cart discount evaluates the cart's actual quantity per product and can apply a tier even for untagged or adjusted carts, which is why the cart and widget can occasionally differ. The checkout price is always the authoritative one.

Putting it together

A typical bundle is an ordered ladder of a few offers: a low rung at full or small discount, a recommended middle rung set as the default, and a higher rung with the deepest discount. Each rung carries its own quantity, discount type, and widget copy. The shopper's pick is tagged on the cart line, and the cart discount applies the right amount at checkout.

For how individual offers calculate savings, see the discount-type articles in this collection.