Using Matrix Bundles

Install it

Install Matrix Bundles from the Shopify App Store. Free for one live bundle. $19 a month for Core, or $29 a month for Core + Discounts, each with a 14-day free trial.

The app runs inside your Shopify admin. Once it is installed you will find it under Apps.

The builder is a block you add in Shopify’s theme editor, so your theme has to accept app blocks. Online Store 2.0 themes do, and it has been walked through to checkout on Horizon, one of Shopify’s own free themes. The one discounted line at checkout does not depend on your theme at all. More on themes.

Make a bundle

Which builder your shop is on

Your shop draws the bundle builder in one of two ways, and both are current and both are supported. A few things below work on one and not the other, so it is worth knowing which you have. Most shops that installed Matrix Bundles recently are on the new builder, and shops that have had it longer move only when someone switches them over — but the How it looks screen is the only reliable answer.

Open How it looks in the app. If you see a section headed Look, with a row of looks to start from and a live preview, and a line reading “Your store uses the new bundle builder”, your shop is on the new one. Anything else — a screen of colour, corner rounding and spacing fields — is the current builder. Do not use the switch-back button as your test: on a shop with a bundle priced on “More items, bigger saving” there is no button there at all, only a line saying why switching back is refused. If you would rather not open the app, look at one of your own bundle pages on a desktop screen at full width. The current builder prints one line reading “20% comes off this bundle at checkout”. If that sentence is nowhere on the page, you are on the new one.

It matters in two places. On this page, a few of the fields below exist only on the new builder, or are labelled differently on each — every one of them says so. And on your storefront, ten of the seventeen settings on the Bundle builder block are drawn in every shop’s theme editor, under a heading that reads “New builder only. No effect on the current one.” That heading is accurate, and nothing in the theme editor tells you which builder you are on. One more, Hide the heading, sits above that heading and does nothing on the current builder either. On the current builder you can set any of these eleven, save, preview, and see no change at all. The values are kept in your theme and start working the moment your shop switches. They are listed separately under “Put the builder on your storefront”.

Switching is a setting, not a rebuild. There is nothing to add to your theme and the block you have already placed draws the new builder by itself. Three things to do first. Set the Bundle id on that block — left blank it is the one thing that breaks: the current builder falls back to a bundle, and the new one draws nothing and leaves a blank space where the builder was. If you have filled in both Subheading and Intro, empty one: on the new builder Intro replaces the subheading, and nothing warns you. And if your Heading contains an asterisk, take it out: on the new builder asterisks mark emphasis and are never shown.

You can switch back from the same screen, and the look you built on the new builder is kept for if you switch again. Your colours, spacing, card width, button style and products per step carry over both ways. One thing stops it: while any bundle uses “More items, bigger saving”, switching back is refused, because the current builder cannot show that pricing. The app calls it “tiered pricing” in that message — it is the same thing. It names the bundles and asks you to give each one a single percentage off or delete it first. Drafts count, so a forgotten draft can block you. Two things do not simply reverse. Custom CSS you wrote for the current builder is kept and applies again when you switch back, but it stops matching anything while you are on the new builder, because the class names are different. And a bundle picture uploaded on the new builder stays on your store, but while you are on the current builder the app will not let you change or remove it — you would have to switch over again to do that.

Open Your bundles in the app and create one. A bundle is a set of steps, and each step is a choice the customer makes. In the app these all sit in one card headed The offer.

• Bundle name — the name customers see. It is the name on the single line in the cart and at checkout, so write it as you want it read.
• The steps — each step matches a collection. Whatever is in that collection on the day is what customers see, and adding a product to it adds it to the bundle with no work in the app. The collection must be published to your Online Store sales channel (Products › Collections, under Publishing): the builder cannot see one that is not. If the step must be filled, customers then see only “This bundle is currently unavailable.” where the builder should be (the page’s source says why), and if it is optional, the step is left out. So do not use a hidden or unpublished collection for a step, even a step with one product in it. A step can be set to match a product tag instead, and the discount still works at checkout, but no builder can draw a tag step: a bundle with one leaves an empty space on the page where the builder should be, on every shop. Use a collection for anything customers build themselves. For each step you also set what customers see above it, and At least — the smallest number they must take from it.
• Items in all — how many products make the finished bundle. This can be higher than the step minimums add up to, and the spare choices can come from any step. That is what lets a bundle be “any four, at least one from each of three”. On the new builder, choosing “More items, bigger saving” replaces this field with a list of tiers, and tier 1’s number of items becomes the number that makes the bundle.
• How they save — on the current builder you see this as a choice with one option available: “Percentage off”, with the percentage itself in the field below, labelled “And they save (%)”. “More items, bigger saving” is shown but switched off, with a line saying it needs the new builder and a link reading “Switch to the new builder on the How it looks screen”. On the new builder both choices are live, and the percentage field is labelled “Percentage off”.
• Status — turn it on when customers should be able to buy it. Until then it stays a draft.

Every one of those fields has more to it than this — what it is called in the app's own records, what it refuses and in what words, and how far it can be pushed. That is all on Configure bundles.

More items, bigger saving

“More items, bigger saving” is on the new builder only. On the current builder you can see it on the screen, greyed out, with a line telling you it needs the new builder and a link reading “Switch to the new builder on the How it looks screen”. Choosing it replaces Items in all with a list of tiers. Each tier takes a number of items and a saving, and tier 1’s number becomes the number that makes the bundle. Each tier can also carry a cart line title, which replaces the bundle’s name on the cart line when that tier is reached.

Every tier has to satisfy all of these, or the save is refused and the app names the tier:

• A bundle can have up to six tiers.
• Every tier must ask for at least 2 items.
• Each tier must ask for more items than the tier before it.
• Each tier must save more than the tier before it.
• A saving must be more than 0% and less than 100%.
• A saving must be a whole number or a half — 15 or 15.5, not 15.25.
• Your step minimums added together may not come to more than tier 1 asks for.

The customer gets the saving of the highest tier they have reached, and it comes off every qualifying item rather than off the tier’s number of items. At a tier of 15% for 3 items, someone buying 5 gets 15% off all 5.

On the bundle page the money on one of these bundles follows the same rule as any other bundle: the exact price, except in the few cases where the builder shows an estimate — see “Change how it looks”, below. If you set the bundle’s “Money shown” to “Percentage only” on its Appearance card, the builder shows the percentage instead of any money.

Once a bundle uses “More items, bigger saving”, your shop cannot switch back to the current builder until that bundle is given a single percentage off or deleted.

Optional steps

Set a step’s At least to 0 and the customer may take nothing from that step. The field says so itself: “0 makes this step optional.” It works on every shop, on both builders.

What it does not do is lower the number of items the bundle needs. Items in all stays exactly where you set it, and the customer makes up the difference from any other step — so a bundle of 1 + 2 with Items in all at 3 still needs 3 items after you set the second step to 0, and all 3 may now come from the first. Lower Items in all yourself if you want the bundle to need fewer. Items a customer does take from an optional step count towards the total like any other.

On the new builder an optional step is labelled Optional where a required one says how many to choose, and it never holds up the Add button. If everything in it is sold out, it stays on the page, marked “Currently unavailable”, and customers build the bundle from the other steps. On the current builder there is no such label, and a step whose collection has nothing to show is left off the page entirely rather than blocking the bundle.

Free gifts

A bundle can come with up to three free gifts. Every complete bundle gets them, and the shopper does not choose them. Open the bundle in the app and find the card headed Free gift, just under The offer. Press “Add a free gift”, pick the product — and its size or colour, if it has more than one — in Shopify’s own picker, and set How many, from 1 to 10. Then save.

The gift costs the shopper nothing: they pay exactly what the bundle costs without it, however the bundle saves. In the builder, the summary shows a line reading “Free:” and the gift’s name, with its picture, and the gift goes into the cart with the shopper’s picks. In the cart and at checkout it is inside the bundle’s one line. If your theme lists the items inside that line, the gift is listed with them. Your shop’s /cart.js does not list them — see “Seeing what is inside a bundle’s line”, under What happens at checkout.

It is free only inside a complete bundle, and only as many as you set. Any more of the same product in the cart cost the normal price, and so does a gift left in the cart after the shopper removes the rest of the bundle. If a shopper adds a bundle that cannot be completed — an item sold out a moment before, say — the builder takes the gift back out of the cart and tells them why.

A gift never stops a bundle selling. If it sells out, the bundle sells without it, and the builder tells the shopper so in one line, such as “Mini Aftercare Balm is sold out, so it isn’t included.” If it is deleted from your store, the bundle sells without it too. The Free gift card marks either one, Sold out or Deleted; remove a deleted gift from the bundle. The gift product must also be published to your online store. If it is not, the builder cannot show it and the bundle sells without it, and the app does not warn you about that one.

Choosing the gift product. The simplest gift is a product you already sell, as it is. Its stock stays in one place, but shoppers can also buy it on its own. A separate product set to Unlisted stays out of your shop’s search and collection pages, though anyone with its direct link can still buy it. It holds its own stock, and some inventory apps will not link an Unlisted product. We have tested gifts only as ordinary, listed products. If you use an Unlisted one, add a bundle to a cart yourself and check the gift arrives before you promote it.

The gift can be a size of a product the bundle already offers — a travel size of a serum you also sell full size, say. Shoppers cannot choose that size in the builder; it only comes as the gift. The app notes this when you save. The gift can also be a product shoppers choose in another bundle. The builder adds the gift on a line of its own, and no bundle counts that line as one of the shopper’s picks, so the app does not warn about it.

A gift card, a product sold only on subscription and a bundle’s hidden product cannot be free gifts. Free gifts need the new builder; the current one does not show them or add them to the cart. See “Which builder your shop is on”, above.

The panel headed What checkout will do shows the gift as free, and what the customer pays: the price of the bundle without it. Shopify’s cart may show a higher crossed-out price than that, because it counts the gift at its normal price. The lines shoppers read about the gift can be changed on What customers read, under Free gifts. What the order shows for a gift, and what that means for returns, is under “What the order records”, below.

The hidden product, and why not to delete it

Turning a bundle on adds one hidden product to your catalogue, named after the bundle. It stands in for the bundle on the single cart line. It is not for sale and should not be edited or deleted. The app sets it to Unlisted, Shopify’s status for a product only its direct link reaches, so it stays out of your shop’s search and collection pages. Leave it Unlisted. Active works too; draft or archived stops the bundle price.

If it is deleted, press Save on the bundle and the app makes a new one. If it is still there but unpublished, a draft or archived, publish or re-activate the one you have rather than deleting it; the app will tell you which it is.

When the bundle is saved it has an ID. Copy it — the storefront block needs it. You will find it on the card headed Bundle ID, or Bundle page if your shop is on the new builder; on a brand-new bundle it appears only once you have saved.

Put the builder on your storefront

Matrix Bundles ships a theme block called Bundle builder, and the app will put it on your theme for you. Open Matrix Bundles in your Shopify admin: on the app’s Setup and status screen there is a step called “Add the builder to your theme”, with buttons for a product page, your home page or a page of its own. Each one opens your theme editor in a new tab with the builder already placed — check it looks right, press Save there, and come back. If your shop is on the new builder that step is called “Create your bundle page” instead, and walks you through making a page for the builder to live on.

To do it by hand, which gives exactly the same result: Online Store › Themes › Customize, open the page you want it on, then Add block › Apps › Bundle builder, and Save. The app’s guide can be dismissed and does not come back, which is why it is written out here too.

What the block’s settings do

The block has seventeen settings, and they are listed here in the order they appear in your theme editor. Six of them work on every shop. Hide the heading, and the ten under the “New builder only” heading, only do anything on the new builder — see “Which builder your shop is on”, above.

• Bundle id — The ID you copied from the app. Always paste it in. Left blank, the new builder draws nothing at all — a blank space where the builder should be. Only the page’s source says why: look for “Matrix Bundles:”. On the current builder a blank Bundle id falls back to the first live bundle it can draw, so you get whichever happens to be first.
• Heading — The heading above the builder. Leave it blank and the bundle’s own name from the app is used instead. Asterisks in this box are turned into emphasis and never shown to the shopper. On the current builder asterisks print exactly as you typed them.
• Hide the heading — Tick it and the heading is hidden from view, while screen readers still read it out. Use it when your page already has a title with the same words, so shoppers do not see them twice. It starts unticked. On the current builder it does nothing, and the heading still shows.
• Subheading — The line underneath it. It is not drawn at all while Intro has anything in it — the two share one slot and Intro wins. Put your text in one box or the other, not both. On the current builder it is always drawn, and there is no Intro box in play.
• Choose button label — The button on each product. It reads “Add” unless you change it.
• Add to cart button label — The button that adds the finished bundle. The bundle’s own wording wins here: if the bundle has a Button label set in the app — on its Appearance card, under “Customise this bundle” — that is what shoppers see, whatever you type in this box. With none set, type your own wording here. Left at “Add bundle to cart”, the builder treats the box as untouched and shows “Add to cart” instead. On the current builder this box is read exactly as you set it, and reads “Add bundle to cart” unless you change it.
• Show only on page — Leave this blank unless you have the same block on several pages. To pin it to one page, type the last part of that page’s web address — for /pages/build-your-routine, type build-your-routine. Blank means it shows on every page built the same way as this one.

Settings the new builder uses

In your theme editor these sit under a heading reading “New builder only. No effect on the current one.” That heading is accurate, and nothing in the theme editor tells you which builder you are on — see “Which builder your shop is on”, above. On the current builder you can set any of them, save, preview, and see no change at all; the values are kept in your theme and start working the moment your shop switches. One more thing worth knowing before you read them: the new builder lays itself out on how wide the block is, not how wide the screen is. In a narrow column on a desktop it uses its narrow layout: one column, with the running totals below the steps instead of beside them.

• Width — How wide the builder is inside the section that holds it. “Fit the section” is the default and adds nothing of its own — the builder fills whatever width your theme’s section gives it. “Contained” caps it at 1,200px and centres it, so there is space either side on a wide screen. “Full width with side padding” leaves the width alone but keeps a space down each side, so the cards never touch the edge of the screen. If you have set Maximum width or Side padding on the app’s How it looks screen, those values are used instead.
• How the steps show — Whether the shopper works down every step on one page or takes one step at a time. “All at once” (stacked) puts them all on the page, and any step can be folded away by tapping its title. “One at a time” (guided) shows the first step only, with a navigator across the top — numbered, unless you have turned step numbers off — and Back and Next buttons underneath. The shopper can jump to any step from that navigator at any point; no step is ever locked. “As the bundle is set” (bundle) is the default and hands the choice to the bundle itself: open the bundle in the app and use “How the steps are shown” on its Appearance card, where the same two choices are called Stacked and Guided. That card appears once the bundle has been saved at least once, so save a new bundle before you go looking for it. Until you change it there, the bundle is stacked. A bundle that draws only one step is always shown all at once, whatever this says. In your theme’s code this setting is called mode, and its values are the words in brackets.
• Eyebrow — One short line above the main heading, set small and letter-spaced. Type it in ordinary sentence case — it is capitalised for you. Leave it blank, as it starts, and no line is drawn.
• Heading emphasis on its own line — Words between asterisks in the Heading — Build *your routine* — are always shown in italics in your accent colour, whether or not this is ticked, and the asterisks themselves never reach the shopper. Ticking this adds one thing: a line break, so the emphasised words start on a new line. Asterisks work in pairs. Leave one unclosed and everything after it is italicised.
• Intro — A few lines under the heading, where bold, italics, links and paragraph breaks are kept. It is held to a comfortable reading width. Anything you put here hides the Subheading, so use one box or the other.
• Heading above the steps — A second heading further down, immediately above the first step — a divider between the introduction and the choosing. It is drawn at roughly two-thirds the size of the main heading. Leave it blank, as it starts, and neither it nor the small label above it is drawn.
• Small label above that heading — One short line above that second heading, in the same style as the Eyebrow. It shows only when “Heading above the steps” has something in it — fill this in on its own and nothing is drawn. Type it in ordinary sentence case; it is capitalised for you.
• Hero image — One picture inside the builder’s introduction, below the heading and the intro text and above the first step, at the full width of the builder. It is not cropped: the whole picture is shown at its own proportions, so a tall image pushes the first step a long way down the page. Choose the shape you want before you upload it. Its alternative text comes from the image’s own alt text in Content › Files, not from anything on this block.
• Pricing strip on phones — A row of small chips under the introduction, one per saving tier, with the tier the shopper has reached filled in your accent colour. It needs a bundle priced on “More items, bigger saving” — a bundle on a single percentage has no tiers to show, so setting this to On shows nothing. “As the style sets it” is the default and follows the bundle’s Appearance card, and then your How it looks screen. On both of those the control is called “Tier strip under the intro on phones”.
• This block is near the top of the page — A loading hint, not a layout setting — nothing looks different either way. Ticked, the browser fetches the builder’s first picture straight away instead of holding it back until the shopper is nearly at it. Tick it only when the builder is what a shopper sees before scrolling. Ticked on a block further down the page, that picture is downloaded even by shoppers who never reach it and competes with the pictures at the top, so the page gets slower rather than faster.

The Bundle link block

Matrix Bundles ships a second theme block, Bundle link. It puts a link, or a small promo card, on your storefront that takes a shopper to the bundle page you have recorded for that bundle in the app — with the product they were looking at already picked for them. It is a signpost: it never adds anything to the cart and never shows a price.

It is drawn by the new builder only. It appears in every shop’s theme editor and you can place it anywhere, but on the current builder it never draws anything, because the page it links to is recorded on the bundle’s Bundle page card and that card exists only on the new builder.

On the new builder the app walks you through it: on the app’s Setup and status screen there is a step called “Link to it from your product pages”. Its recommended placement is by hand, because no Shopify link reaches inside your product details — in your theme editor, open a product that is in your bundle, select the part that holds the title and price (in Horizon themes that is Product information, then Product details), choose Add block › Apps › Bundle link, move it where you want it, for example under the price, and Save.

• Bundle id — Paste a bundle’s ID here to pin the block to that one bundle. Leave it blank and the block uses the first bundle in your list that qualifies: the order on the app’s Your bundles screen (“Order tried”), not alphabetical. On a card outside a product page, set it: otherwise moving a bundle up or down, or another edit to your bundles, can change which bundle the card promotes, with nothing to tell you it has.
• Style — Two choices, and it starts on “Link (product pages)”. Link draws one underlined line of text and nothing else. “Card (collection or home page)” draws a bordered box that is itself one link, stacking the picture, the bundle’s title, the link text and a button — a shopper clicking anywhere on it goes to the same place. The labels are guidance rather than a rule: a Card will also draw on a product page, and a Link on a page with no product draws nothing.
• Button label — The words on the Card style’s button, and nothing else. Leave it blank and the button says “Build yours”. On the Link style it has no effect.
• Card image — The picture on the Card style. Choosing one while Style is set to Link has no effect anywhere. Its alternative text comes from the image’s own alt text in Content › Files, not from this block.
• Wording — The link’s own words have no setting on this block. Out of the box a link reads “Part of the Aftercare Routine · save 20% ›”, with your bundle’s name and its saving filled in. A bundle with two or more saving tiers reads “save up to” and its biggest saving instead. To change the words, open the bundle in the app and use “Link text on product pages” on the Bundle page card. It is optional, up to 100 characters, and {bundle_title} and {max_percent} are filled in for shoppers — write {max_percent}, not {max_percent}%, because the per cent sign is added for you. On a card your wording replaces the middle line only, not the title and not the button. The button’s words are the Button label setting, above.

A Bundle link draws nothing anywhere in your shop, on any page, in any of these cases:

• Your shop is on the current builder. The block still appears in your theme editor and can be placed, but it has no page to link to until you switch. See “Which builder your shop is on”, above.
• No bundle page has been recorded against the bundle. Open the bundle in the app and set it on the Bundle page card, in “The page this bundle is built on” — paste the page’s web address, or just the part after /pages/.
• One of the bundle’s steps matches products by tag instead of by collection. One tag step is enough to switch the block off for that bundle everywhere, as a link and as a card. Change that step to a collection in the app; the builder cannot draw a tag step either.
• The bundle is still a draft. Only live bundles are ever considered. Set it live.
• The bundle leaves out a collection that is no longer there, or that is not published to your Online Store sales channel. That switches the block off for the whole bundle everywhere, including on products that were never left out. Open the collection in Products › Collections and, under Publishing, tick Online Store — or remove it from the bundle’s exclusions.

On the Link style the block also decides per product, and drawing nothing on a particular product is correct behaviour rather than a fault:

• The product whose page it sits on is not in any of the collections the bundle’s steps point at. Add the product to one of those collections and the link appears on the next page load, with nothing to save in the app.
• The product has nothing available to buy, is subscription-only, or is a gift card. A product that sells out loses its bundle link until it is back in stock.
• The bundle leaves out a collection or a tag and the product on the page matches it. Nothing to do — you would not advertise a bundle this product cannot join. It looks exactly like a broken block, which is why it is listed here.
• The Style is set to Link on a page with no product at all, such as your home page. Choose Card instead.

Whatever the reason, the live page says nothing — the block simply takes up no space. The theme editor is the only place it explains itself, and even there it names two of the reasons rather than all of them. If a placed block is blank, open Online Store › Themes › Customize and look at it there.

Adding a bundle from your own button

Items added through the new builder are labelled with the bundle they were chosen in, so checkout counts them towards that bundle first. If your theme adds a bundle’s items with its own button, for example a fixed set sold from its own product page, give every item the line property _mx_for, set to the bundle’s ID. Open the bundle in the app to copy the ID. Checkout then tries that bundle first for those items, so the cart line shows that bundle’s name, saving and free gift.

• In a product form: add <input type="hidden" name="properties[_mx_for]" value="BUNDLE-ID">
• With the Ajax API: send "properties": { "_mx_for": "BUNDLE-ID" } on each item.
• With the Storefront API: send the attribute { "key": "_mx_for", "value": "BUNDLE-ID" } on each line.
• If the set comes with a free gift: add the gift on its own line with _mx_gift_for set to the same ID.

The underscore keeps both hidden from shoppers in the cart and at checkout. The property only chooses which bundle is tried first:

• Give it to every item of the set. The bundle is tried first only with the items that carry it, and those items must meet its rules on their own.
• Items without it are offered to your bundles in the usual order. Any the bundle counts that are still left when its turn comes join it, so an extra item added from a product page still counts and can lift the saving to a higher tier.
• If the items that carry it don’t meet the bundle’s rules, or the bundle is a draft or has been deleted, they are treated as if the property were not there.
• If your theme or an app handles adding to the cart itself (its own Shopify.actions.updateCart handler, or code that cancels matrix:bundle:addtocart and adds the lines), pass each line’s properties through unchanged. Without them the items are offered to your bundles in the usual order, and the cart line can get another bundle’s name and saving.

The current builder labels nothing it adds, so on a shop still using it every item goes to your bundles in the order on the Your bundles screen, including a basket built in a bundle’s own builder. Switch to the new builder on the app’s How it looks screen first.

How it looks, and the words customers read

Change how it looks

Open How it looks in the app. It sets how the builder looks on every bundle page in your shop, and what you find there depends on which builder your shop is on — see “Which builder your shop is on”, above.

On the current builder it is four cards: Colour, Shape and spacing, What each step shows, and Your own CSS. Change what you want and press Save in the bar across the top.

On the new builder the screen has a live preview and starts with a section headed Look: seven ready-made looks called Native, Routine, Soft, Bold, Mono, Night and Brand. Native is where a shop starts, and it lets your theme’s own fonts and colours decide wherever you leave a setting alone. Pick a look, then change anything under it — Colours, Typography, Shape and space, Cards, buttons and stepper, and the summary panel beside the steps. Your own CSS is under Advanced.

A line of your own on each product card. On the new builder a card can show a short extra line of text, called the Descriptor. Open How it looks, go to Cards, buttons and stepper, and under The product card tick Descriptor in Card fields. Then choose its Descriptor source: Product type, or A metafield. For a metafield, type its name in Descriptor metafield, such as custom.subtitle, and fill it in on each product. The Routine look has the Descriptor on already, showing the product type. Cards have no Details link, so if What customers read lists “Details link on product cards” under “Wording you saved that isn’t used”, that is why; use the Descriptor instead.

Prices, on the new builder only. The builder shows the exact price a shopper will pay, in your shop’s own money format: three items that cost £52.97 together, at 15% off, show as £45.02, the penny Shopify charges. It shows an estimate instead, such as “about £45.02”, with a line saying the cart shows the final price, when the last penny could come out differently at checkout. That happens in five cases:

• the shopper is paying in a currency other than your shop’s own;
• their cart already holds something this bundle could take in at checkout;
• a live bundle you made before this one could take the same products;
• your shop’s currency does not use two decimal places, such as the yen;
• the shopper chooses the size, colour or other options of a product that has more than 30 variants.

If you would rather every shopper saw estimates, open How it looks and find Prices, the first part of the Advanced section. Press Show estimates instead and confirm. It changes what shoppers see on your live shop straight away, and Show exact prices puts it back. Before 28 September 2026 estimates were the default, so if your shop showed them then, it shows exact prices now unless you choose estimates again.

Your own CSS

On the new builder, How it looks has a box for your own CSS under Advanced, up to 8,000 characters. It is added to the page after the builder’s own styles. Start every rule with .mx-v2, as the builder’s own rules do, or yours will lose to them: .mx-v2 .mx-intro { display: none } hides the heading and intro above the steps, and .mx-intro { display: none } on its own does nothing.

These are the names you can target. They stay the same when the app updates:

• .mx-v2 — start every rule with it, as in .mx-v2 .mx-card { … }; without it the builder’s own rules win over yours
• .mx-bundle — the whole builder
• .mx-bundle--{bundle id} — one bundle only
• .mx-intro — the heading, eyebrow and intro above the steps
• .mx-nav — the step progress; each step is .mx-nav__c, with .is-done once done and aria-current on the one showing
• .mx-stage — one step
• .mx-card — one product (gains .is-picked when chosen)
• .mx-add — a product’s Add button
• .mx-sum — the summary panel
• .mx-slot — one summary slot
• .mx-cta — the main button
• .mx-bar — the bar on phones
• [data-mx-part] — the parts the preview names, such as [data-mx-part="intro.heading"]

Other names inside the builder may change in an update, so a rule that relies on one can stop working without warning. Many settings on How it looks are also CSS variables you can use in your own rules, such as var(--mx-color-accent); the screen lists them all under “What you can target”, next to the CSS box.

Starting with .mx-v2 is not always enough. Some of the builder’s rules depend on a setting you chose, and those are more specific than a rule that starts with .mx-v2 alone, so yours loses there. That is true of Main button style, Add button style, Card style on computers, Card style on phones, Summary position, Summary on phones and tablets and a few others. For example, when Main button style is Outline, .mx-v2 .mx-cta { background: #000 } does nothing.

So change the setting first; it may already do what you want. For the step progress, the colour of done and current steps, the line and steps still to do, the marker size and the marker corners are under Steps, summary and bar, in Colours, size and corners, just below Step progress. If you still need a rule of your own, repeat the setting in it. The builder writes each setting on the .mx-v2 element, where your browser’s page inspector shows it, so .mx-v2[data-mx-cta="outline"] .mx-cta { background: #000 } works. These setting names are not on the list above, so check such a rule after an app update. A part in a certain state has rules of its own too, such as a chosen card (.is-picked) or an Add button that cannot be pressed (:disabled), so add the state to your rule in the same way.

Change the words customers read

What customers read holds every word a shopper sees in the bundle builder, in each language your shop sells in: the wording every bundle shares, and each bundle’s own. Choose a language, change the boxes you want, and save that language before you move to another.

Where you write nothing for a language, shoppers see English. It works on the new builder only: on the current builder the screen says so, and there is nothing to change, because that builder does not read its wording from there.

What happens at checkout

The price and the single cart line are worked out by Shopify itself, not by your theme. That is why they hold on checkout routes that never run your theme’s code — a cart built without the builder still arrives as one merged, discounted line. What is not decided there is refusal: the rules about what makes a valid bundle are checked in the builder as the shopper picks, and a basket that does not match them is simply not turned into a bundle. Nobody is blocked; they pay the normal price for the separate items.

Discount codes on top of a bundle

The bundle price is not a discount, so a discount code can still come off on top of it. A code limited to certain collections or products works differently from one for everything. In the cart a bundle is one line, and that line belongs to the bundle’s hidden product, not to the products inside it. So a limited code comes off a bundle only if the hidden product is in one of the code’s collections, or is one of its chosen products. The products inside the bundle being in that collection is not enough.

Being hidden from your shop’s collection pages does not keep the hidden product out of a collection. It is priced at 0.01, so an automated collection whose rule is any price above 0 takes it in by itself, and a code limited to that collection then reaches your bundles too. To let a limited code reach bundles, add the bundles’ hidden products to one of its collections; to keep it off them, keep them out. Every hidden product has the product type Matrix Bundles helper, so you can filter your product list to find them. Then try the code on a real basket before the promotion goes live.

Seeing what is inside a bundle’s line

Your shop’s cart data at /cart.js, which themes and testing tools read, shows a bundle as one item: its hidden product, at the bundle’s price, marked has_components. It does not list the items inside, so a free gift never shows there. To see them, open the order in your Shopify admin, where every item is listed on its own. Your cart page lists them too if your theme shows the items inside a bundle’s line. Horizon, one of Shopify’s own free themes, does.

Where bundles do not apply

Some of these are Shopify’s limits rather than ours, and none of them have a workaround worth pretending to:

• Subscriptions. An item bought on a selling plan is never counted towards a bundle, merged into one or discounted by one, so a bundle cannot also be a subscription. The rest of the cart is unaffected. That is a platform rule, not a choice we made.
• Orders created or edited in the admin. Bundling does not run on the Create Order API or when an existing order is edited, so support cannot add an item to a bundle after the fact.
• Other sales channels. The price and the single cart line are worked out by a Shopify cart function, so a bundle only happens where one of your online store’s carts does. We have tested the online store and its checkout. Anywhere else, do not build a promotion that depends on bundling until you have tested that channel yourself.

What the order records

One line in the cart, every product on the order. The order records each product separately, grouped to the bundle it came from — which is Shopify’s own design for bundles, and it is what keeps the rest of your store working.

Stock moves per product. Your pick list names real products. Refunds and returns operate per product. Sales reporting counts the products rather than an invented bundle SKU, so the quantities reconcile with what you shipped. The discount is taken off the bundle as a whole, so the per-product money on the order is Shopify’s split of it rather than each product’s usual price.

A free gift is on the order with the other items in its bundle, and its stock goes down like theirs. Shopify spreads what the customer paid across every item in the bundle, the gift included, so the gift’s line shows a share of the price rather than £0. The order total is right. If a customer returns only the gift, Shopify refunds that share, so if customers can start returns themselves you may want a rule that a free gift cannot be returned on its own. Tax follows the same split: if the gift is taxed differently from the other items, the tax on the order can differ a little. The app warns you when you save a gift that charges no tax.

If something is not right

• The builder is not showing. Check the block is on the page you are actually looking at, and that “Show only on page” is either blank or exactly that page’s web-address ending. Then check the Bundle id: if it names no live bundle — a typo, a trailing space, a bundle set back to draft — the builder draws nothing. Copy the ID again from the bundle in the app. Then check the bundle’s collections, because the builder also draws nothing when a step’s collection is empty, or is not published to your Online Store sales channel, or when a collection the bundle leaves out is not published to the Online Store. Open each collection in Products › Collections and, under Publishing, tick Online Store. Where the block names a bundle, customers see “This bundle is currently unavailable.” in its place (you can change the words in the app). The page gives the reason in its source: view the page source and look for “Matrix Bundles:”. The theme editor says it too: open Online Store › Themes › Customize, go to the page and click the Bundle builder block. On the current builder that message reads “No live bundle yet. Create one in Matrix Bundles and set it live” even when you have live bundles — it means this block’s ID matches none of them, not that you have none. The current builder also draws nothing when a step that must be filled has nothing a customer can buy, and the live page doesn’t say why.
• The button says a step is unavailable. Nothing in that step can be bought right now: every product in it is sold out, or is a gift card, a product sold only on subscription, or one the bundle leaves out. The step says “Currently unavailable”, its products show greyed, and the button stays off, so the bundle can’t be added until one of them can be bought again. Restock one, or add another product to the step’s collection. A step with At least set to 0 is marked the same way, but it doesn’t hold the bundle up. The app’s live preview says the same above the builder. On the current builder the whole builder disappears instead.
• The discount has not come off. Nothing is ever refused — a basket that does not qualify is just a normal basket, so there is no error to see. Check, in this order: the bundle’s hidden helper product is published to your online store and is Unlisted, as the app leaves it, or Active — not a draft or archived (the bundle’s own screen in the app says so if it is); the basket really holds enough items for Items in all, and enough from each step; and nothing in it is bought on a subscription, is a gift card, or is a product the bundle leaves out — those are never counted towards a bundle, though the rest of the basket still is.
• A discount code misses the bundle. The code is limited to certain collections or products, and the bundle’s hidden product is not among them. A code judges the bundle’s one line by its hidden product, not by the products inside it. See “Discount codes on top of a bundle”, under What happens at checkout.
• The hidden bundle product was deleted. Press Save on the bundle and the app makes a new one. If it is still there but unpublished, a draft or archived, publish or re-activate the one you have rather than deleting it; the app will tell you which it is.
• Customers cannot buy it. The bundle is still a draft. Turn it on.
• The Bundle link block shows nothing. Work down the two lists in the Bundle link section above. If your shop is on the current builder the block can never draw, whatever you do to it. Otherwise a tag step, a missing bundle page and a draft bundle are the three commonest. The live page gives no clue, so check the block in the theme editor, where it explains itself — though even there it names only two of the reasons.
• The Subheading has vanished. You are on the new builder and the Intro box has something in it. The two share one slot and Intro wins. Empty the Intro, or move your words into it. This also happens the moment a shop switches builders with both boxes filled, and nothing warns you.
• Part of a heading is in italics. On the new builder, asterisks in the Heading mark emphasis and are never shown to the shopper. They work in pairs — if you opened one and did not close it, everything after it is italicised. Remove the stray asterisk. On the current builder asterisks print exactly as typed, so a heading that looks right on one builder can look wrong on the other.
• The pricing strip does not appear on phones. It draws one chip per saving tier, so a bundle on a single percentage has nothing to show — change it to “More items, bigger saving” first. If the bundle does have tiers, check “Saving tiers” in two places: on the bundle’s own Appearance card, and shop-wide on the How it looks screen. Set to “Not shown” in either one, it turns the phone strip off as well, and the block’s own On cannot bring it back. One more thing: the strip follows how wide the builder is, not how wide the screen is, so it appears in a narrow sidebar column on a desktop and may not appear in a full-width section on a small laptop.
• A new setting changed nothing on the storefront. Your shop is on the current builder. Eleven of the seventeen settings on the block are for the new builder and do nothing on the current one, and nothing in the theme editor tells you which you have. Open How it looks in the app — see “Which builder your shop is on”, above. What you set is kept and starts working if you switch.
• The free gift is not showing. Open the bundle in the app. Its Free gift card marks a gift that is sold out or deleted, and either way the bundle sells without it. If the card shows nothing wrong, check the gift product is published to your online store: the builder cannot show one that is not, and the app does not warn you about that. Free gifts also need the new builder. The current one never shows them.

Support

The support page answers the questions that come up most, including where the app behaves differently from what you would expect. If yours is not there, email support@matrixhealthgroup.co.uk and a person will answer.

The app holds no customer or order data, and asks Shopify for no permission to read either, so we cannot open your store and look for ourselves. Your store address, the bundle you are asking about and what you saw happen are what we have to work with.

More on this app

This page covers the app as you use it day to day. These carry the rest.

• Configure bundles — Every setting a bundle has, what it is called in the app's own records, every limit and the exact words the app refuses in — and each of them written as JSON as well.
• Connect an assistant — How an assistant or a program reaches the app from outside it, what it can ask for, and how a merchant makes and revokes a key. The API and the assistant connector are switched on. Claude and ChatGPT connect by signing in, and the merchant approves them inside their own Shopify admin. Anything else uses a key the merchant makes on the app’s Access keys screen.
• Matrix Bundles from a terminal — The same jobs as commands rather than clicks: getting a key, reading and changing bundles, trying a change before it is saved, and what each refusal means. The API and the assistant connector are switched on. Claude and ChatGPT connect by signing in, and the merchant approves them inside their own Shopify admin. Anything else uses a key the merchant makes on the app’s Access keys screen.
• How to let customers build their own bundle — The whole set-up as eight short steps, from the collection to a bundle a customer can buy.
• Matrix Bundles and Shopify Bundles compared — What Shopify’s free Bundles app does, what this app does, and when the free one is the right choice.
• Discount rules — What a discount rule takes off, how two rules on one item are added together, and the ceiling on that total. Discount rules are switched on, on the $29 a month plan. Open Discounts in the app to make one.