Bundles and Upsells on a Headless Shopify Storefront

On a headless Shopify storefront, bundle and upsell offers split into two parts. The pricing still happens inside Shopify: discounts applied by Shopify Functions run on the cart and at checkout whatever front end created the cart. The display does not carry over, because app blocks belong to Shopify themes and a custom storefront has no theme, so your developers fetch the offer data and render the interface themselves. This guide covers what changes, what stays the same, what you need to build, and how to keep the price on your page equal to the price at checkout.

What changes when the storefront is headless?

The display layer. On a theme, a bundle app shows its offers through an app block that the merchant places in the theme editor. A storefront built with Hydrogen or another framework does not render theme blocks, so nothing appears until someone builds it.

That moves three jobs from the app to your team:

• Fetching the offers that apply to the product or cart being viewed.
• Rendering them as components in your own design system: tier selectors, bundle cards, add-on checkboxes.
• Adding the right lines to the cart when the shopper accepts an offer.

What stays the same?

The part that decides what the customer pays. A headless storefront still uses Shopify's cart and Shopify's checkout. Automatic discounts, including those applied by Shopify Functions, are evaluated by Shopify against the cart's contents.

That has two useful consequences:

• An offer configured once in the Shopify admin prices the same way on a theme storefront and a custom one.
• Your front end never needs to be trusted with pricing. It shows the offer and adds the items; Shopify applies the discount.

How do offers reach a custom storefront?

Through an API. The bundle app has to expose its offer definitions in a form your storefront can request: which products an offer targets, its tiers or components, and the discount at each level. Your storefront then fetches that data and draws the offer.

Before choosing any bundle app for a headless build, ask the vendor three questions:

1. Is there supported access to offer data from a custom storefront, and on which plan?
2. Are the discounts applied by Shopify at checkout, or calculated by the app's own script on the page? Only the first survives the move to headless.
3. What does the cart need to contain for the discount to apply: plain product lines, or lines carrying particular attributes?

For Marka Bundles & Upsells, headless storefront access is part of the Scale plan, the top plan. On the other plans, offers are shown through the theme app block. In both cases the discount is applied at checkout by Shopify Functions.

What do you need to build?

Four pieces, each small on its own.

1. A data loader. Fetch the offers for a product alongside the product itself, on the server where your framework allows it, so the offer arrives with the page and does not pop in afterwards.
2. Offer components. One per offer type you run: a quantity-break selector, a bundle card, an add-on row.
3. Cart actions. Accepting an offer adds or updates cart lines through Shopify's cart API, exactly as your normal add-to-cart does.
4. Cart display. Show each line's discounted price and the name of the discount, read from the cart Shopify returns.

The layout principles are the same as on a theme: offer near the button, savings in currency, single unit always visible. They are set out in how to display bundle offers on a product page.

How do you keep prices consistent with checkout?

Treat Shopify's cart as the only source of prices once something is in it.

It is reasonable to show the offer's advertised prices on the product page from the offer data: three for $48. From the moment the items are in the cart, stop calculating. Read the line prices and discount amounts from the cart response and display those. If your own arithmetic and Shopify's ever disagree, Shopify's figure is the one the customer will be charged, so it is the one to show.

The usual causes of a mismatch on headless builds:

• Stale offer data. The page was cached before the offer was changed or ended. Give offer data a short cache life, and revalidate when offers are edited.
• Rounding done twice. Your code rounds a per-unit price, then multiplies. Shopify discounts the line. Display Shopify's line total.
• Currency. The offer was fetched for one market and shown in another. Request offers in the same country and language context as the product.

Stores selling in several languages have further display work, covered in translating bundle offers for multiple languages and markets.

What should happen when the offer data is unavailable?

The product page should render and sell as normal, without the offer. An API call for offers must never block the add-to-cart button.

• Set a timeout on the offer request and render without it if the timeout passes.
• Do not leave an empty box or a spinner where the offer would be.

Is headless worth it for bundles alone?

No. Nothing about bundles requires a custom storefront, and a theme gives you the display for free. Go headless for reasons that justify the build and its upkeep, and then make sure your offers come with you. If you are weighing that decision, our Hydrogen and headless service covers that kind of build, and the guide to Shopify bundle types covers the offers themselves.

A short checklist

1. Confirm your bundle app offers supported headless access, and on which plan.
2. Confirm discounts are applied by Shopify at checkout.
3. Load offer data with the product, on the server where possible.
4. Build components only for the offer types you use.
5. Display cart prices from Shopify's cart response, never from your own sums.
6. Render the page without the offer if the request fails.
7. Test every tier through to checkout in each market.

Headless changes who draws the offer, and leaves the pricing with Shopify. If you want the offers managed in the Shopify admin and available to a custom front end, look at the Scale plan of Marka Bundles & Upsells.