How adding a bundle to the cart works

When a shopper clicks Add to cart on a product that has a Bundlex deal, the widget does more than add a single variant. It quietly takes over your theme's add-to-cart request so the main product and any extras or free gifts land in the cart together, with each line tagged so the right discount applies at checkout. This page explains what happens under the hood.

The hidden marker on your product form

When the widget loads on a product page, it injects a hidden input named bx-product-form into your theme's product form. This marker is how Bundlex knows which add-to-cart requests belong to a bundle and which it should leave completely alone.

Bundlex watches the add-to-cart requests your theme sends and only steps in when two conditions are both true:

• The request goes to the /cart/add endpoint.
• The request body contains the bx-product-form marker.

If either condition is missing, Bundlex does nothing and your theme's normal add-to-cart runs as usual. That is why a theme that strips hidden form fields, or one that posts to a non-standard endpoint such as /cart/change.js, can prevent the bundle from being added even when the widget is visible.

Adding the main item plus extras and gifts

Once Bundlex confirms the marker, it adds every item in the selected offer: the main product, any paid cross-sells, and any free gifts. They go into the cart as part of the same add-to-cart action rather than as separate, disconnected clicks, so the shopper sees the whole bundle appear at once.

To do this, the widget reads which variants and extras the shopper selected, then builds the cart request from that selection. The customer never has to add the gift or the cross-sell manually. Selecting the offer is enough.

Tagging each line for the checkout discount

Adding the items is only half the job. Bundlex also attaches a hidden _bundlex property to each cart line. This tag is what lets the separate cart-discount Shopify Function recognise the bundle and apply the correct discount when the shopper reaches checkout.

The tag carries a small set of fields:

• Offer index tells the cart Function which tier the shopper picked, so two offers that share the same quantity can still be told apart.
• Extra index appears on gift and cross-sell lines so each extra is matched to its own configuration in the offer. It also keeps two extras that happen to use the same variant from collapsing into one cart line.
• Discount id lets each cart Function ignore lines tagged for a different Bundlex discount, so two bundles on the same store do not interfere with each other.

These codes are internal. They are hidden from customers, used only for applying the discount and for revenue attribution, and they cannot be removed from the admin.

Working with your theme and other apps

Bundlex is built to slot into your existing add-to-cart flow without breaking it. The interception handles the three request body formats Shopify themes commonly use:

• JSON
• FormData (multipart form submissions)
• URL-encoded form data

Whatever format your theme sends, Bundlex reads the marker from it and sends the cart request back in that same format, so your theme's request stays valid.

Crucially, Bundlex preserves the line-item properties and selling_plan value that other apps add to the request. So custom text, uploaded files, engraving messages, and subscription selling plans set by other apps are carried through onto the main bundle item rather than being dropped. The original request is also allowed to complete normally, which keeps cart drawers, sidebars, and refresh logic from other apps working as they should.

Quantity must match a tier exactly

A bundle is only added when the quantity matches one of the offer's tiers exactly. There is no nearest-offer fallback. If the quantity does not line up with a configured tier (for example, Buy 1, Buy 2, or Buy 3), the offer is deselected and no bundle discount is applied. This is intentional, and it is the most common reason an expected discount does not appear. If a customer changes the quantity to a number that is not one of your tiers, Bundlex steps back and the cart behaves like a normal add-to-cart.

In short: the hidden marker tells Bundlex which requests are bundles, the interception adds every item in the offer together, and the per-line tags let the cart Function apply the right discount at checkout. The discount itself is calculated and applied at checkout by the Shopify Function, not on the product page.