How adding a bundle to the cart works

When a shopper adds a selected offer, Bundlex builds one cart request containing the main products, required bundle products, free gifts, and selected upsells. Each line carries the information needed to check eligibility and calculate its discount.

How Bundlex recognizes the product form

The widget adds a hidden bx-product-form marker to the product form and watches requests to Shopify's /cart/add endpoint. The marker is the usual way to recognize a bundle submission.

Some themes rebuild a request and drop hidden fields. Bundlex also has a narrow recovery path for a recent add-to-cart action on the marked form when the requested variant and current selection still match. A missing marker is a useful diagnostic clue, but does not by itself mean the bundle cannot be added.

This recovery does not apply to every custom request or to add-ons-only mode. If a visible offer adds the wrong items, see add-to-cart troubleshooting.

Adding the selected products

Bundlex reads the shopper's selected variants, quantities, and optional extras, then builds the bundle payload. The items are added together rather than through a sequence of separate shopper clicks.

If Shopify rejects a nested add, Bundlex can retry without parent relationships. If an extra is still unavailable, recovery can retry the main products while preserving their discount information. A rejected add does not always result in one full-price product; the outcome depends on which retry succeeds and whether the remaining cart qualifies.

How checkout recognizes the offer

Cart lines carry a private _bundlex property identifying the discount, offer, and any extra. This distinguishes offers with the same quantity, keeps separately configured extras identifiable, and isolates tagged lines from other Bundlex discounts.

Checkout uses the actual cart contents to check quantities, required products, and eligibility. The tag also supports revenue attribution. Shopify hides private line properties at checkout; theme and custom template code must filter them elsewhere. See Bundlex order codes.

Custom properties and subscriptions

The integration handles common JSON, FormData, and URL-encoded add requests. Text properties, such as engraving messages, and supported selling-plan values can be carried onto the main products.

File uploads need a compatibility check. The normal bundle request rebuild does not preserve uploaded File values as uploads, so do not assume a file-upload or personalization app will work just because its text fields do. Test the complete flow and contact support with the product URL.

Which quantity reaches the cart

• Bundlex quantity selector active: the widget's stepper controls quantity, and the theme input reflects its result.
• Usual tier-navigation setup: an exact native quantity can select a matching tier. An in-between value can leave the previous offer selected, so the offer's configured quantity may be added.
• Support-enabled native quantity for plain tiers: some stores use a separate setup that preserves a shopper's typed quantity.

With optional selection enabled and no offer selected, the theme's controls work normally and offer gifts or extras are not added. Plain quantity discounts can still apply at checkout if the cart qualifies. Deselecting an offer is not an opt-out from all discounts.

See theme quantity behavior and Bundlex's quantity selector to choose the setup you need.