Developers
JavaScript API
BundleM8's storefront JavaScript API lets developers build a completely custom bundle experience, or add behaviour around the standard form. This page is for developers comfortable editing theme code.
There are two ways to use it:
- Build your own form with the API's methods, using the Bundle Selection block's Metadata only setting.
- Listen for events from the standard bundle form, for example to update other parts of the page or send analytics.
Building your own form
1. Add the bundle data to the page
- In the theme editor, add the Bundle Selection block to your bundle product template.
- Turn on Metadata only in the block's Advanced settings.
- Make sure the BundleM8 Scripts app embed is on.
With Metadata only on, the block doesn't show a form. It adds a <bundle-metadata> element containing the bundle's data, and exposes the API.
2. Get the API
Call window.bundlem8() with the bundle's product ID:
const bundle = window.bundlem8(productId)
| Parameter | Type | Description |
|---|---|---|
productId | number or string | The bundle product's numeric ID, such as {{ product.id }} in Liquid |
index | number | Optional. Which block to use if the same bundle appears more than once on the page, starting at 1. Defaults to the first |
3. Wait for the bundle to be ready
Before using the API, wait for two things:
- The BundleM8 script. It loads with
defer, so your theme's scripts can run before it.customElements.whenDefined('bundle-metadata')waits until it has loaded. - The bundle's data. For most bundles this is already on the page. Bundles with more than 600 linked variants load their data from BundleM8 after the page opens instead.
bundle.readywaits for either case.
async function loadBundle(productId) {
await customElements.whenDefined('bundle-metadata')
const bundle = window.bundlem8(productId)
if (!bundle || !(await bundle.ready)) {
// The block isn't on the page, or the bundle's data couldn't be loaded.
return null
}
return bundle
}
loadBundle(productId).then((bundle) => {
if (!bundle) {
showMessage('This bundle is unavailable right now. Please refresh the page.')
return
}
buildForm(bundle)
})
bundle.ready is a promise that resolves to true once bundle.context is available, or false if the data couldn't be loaded. For bundles whose data is on the page, it resolves straight away, so the same code works for every bundle.
Your form has to wait for a large bundle's data to arrive, so show a loading state until ready resolves:
const form = document.querySelector('#my-bundle-form')
form.setAttribute('aria-busy', 'true')
form.textContent = 'Loading bundle options…'
const bundle = await loadBundle(productId)
form.removeAttribute('aria-busy')
form.textContent = ''
if (bundle) {
buildForm(bundle)
}
Keep using the same object
bundle.context and bundle.inventory always return the latest data, so the object returned by window.bundlem8() stays up to date after ready resolves. You don't need to call window.bundlem8() again.
4. Build your form from the bundle's data
bundle.context describes the bundle's groups and products. Render your form from it, then call the API's methods as the customer makes choices.
const bundle = await loadBundle(productId)
// Fixed products are always included. Add them for every group that's shown.
bundle.context.groups
.filter((group) => bundle.isShown(group.id))
.filter((group) => group.variants.some((variant) => !variant.optional))
.forEach((group) => bundle.addIncludedProducts(group.id))
// When the customer ticks an option
function onOptionChange(groupId, guid, checked) {
try {
checked ? bundle.selectProduct(groupId, guid) : bundle.removeProduct(groupId, guid)
} catch (error) {
// For example, "This group has reached its selection limit."
showMessage(error.message)
}
// Show or hide nested groups to match the new selection.
bundle.context.groups.forEach((group) => {
groupElements[group.id].hidden = !bundle.isShown(group.id)
})
priceElement.textContent = bundle.formatMoney(bundle.total())
}
// When the customer fills in a custom field
function onFieldChange(groupId, property, value) {
try {
bundle.setField(groupId, property, value)
} catch (error) {
// For example, "Name can't be longer than 20 characters."
showMessage(error.message)
}
}
// When the customer adds the bundle to their cart
addButton.addEventListener('click', () => {
if (bundle.missingFields().length > 0) {
showMessage('Please fill in the required fields.')
return
}
bundle.addToCart({
quantity: 1,
onSuccess: () => openCartDrawer(),
onError: () => showMessage('Something went wrong. Please try again.'),
})
})
Check the group rules yourself
The API stops customers going over a group's maximum, adding the same product twice, choosing in a hidden nested group, or entering a custom field value that isn't allowed. It doesn't check minimum selections or required custom fields before adding to the cart. Check each shown group's min, and missingFields(), before calling addToCart().
API reference
Properties
| Property | Type | Description |
|---|---|---|
id | string | The bundle product's ID |
ready | Promise<boolean> | Resolves to true once the bundle's data is available, or false if it couldn't be loaded. See Wait for the bundle to be ready |
context | object | The bundle's groups, products, price range and bundle price. Always the latest data. See Bundle data |
inventory | array | Stock information for every variant in the bundle |
selected | array | The products currently in the customer's bundle |
branches | array | The condition branches the customer has chosen |
fields | array | The custom field answers that will be added to the cart, each with a property and value. Leaves out answers in groups that are hidden |
config | object | The store's money format and currency settings, and bundlePrice: the bundle's bundle price, or null if it has none |
isShown(groupId)
Returns true if the group should be shown to the customer, given their current selection. Top-level groups are always shown. A nested group is shown when:
- Its parent is a condition group, and the customer has chosen the branch linked to it. A nested group no branch links to is shown once any branch is chosen.
- It's set to show for one product, and the customer has selected that product.
- Otherwise, the customer has selected enough optional products in the parent to meet its minimum, and at least one. Fixed products don't count, unless the parent only has fixed products. Then its nested groups are always shown.
The parent must be shown too. This is the same rule the standard form and the cart use, so call isShown() after every change to show and hide groups, rather than working it out yourself.
Throws an error if the group doesn't exist.
addIncludedProducts(groupId)
Adds a group's fixed products to the customer's bundle. Call this for every group with fixed products that's shown to the customer, including nested groups once they become visible.
Throws an error if the group doesn't exist, or if it's a nested group that isn't shown.
removeIncludedProducts(groupId)
Removes a group's fixed products from the customer's bundle, along with selections in any groups nested under it.
selectProduct(groupId, guid)
Adds an optional product to the customer's bundle. guid is the product's guid from context.
Throws an error if:
- The group or product doesn't exist, or the product is fixed.
- The product is already selected.
- The group has reached its maximum selections.
- The group is nested and isn't shown. See isShown().
removeProduct(groupId, guid)
Removes an optional product from the customer's bundle. If a nested group is no longer shown as a result, for example because the parent has dropped below its minimum, that group's selections are removed too.
selectCondition(groupId, branchId)
Chooses a branch in a condition group. branchId is the branch's id from context. Throws an error if the branch doesn't exist, or if the group already has a branch chosen. Remove the current branch first.
removeCondition(groupId, branchId)
Removes a chosen branch, and clears selections in the group linked to it.
total()
Returns the price of the products currently in the customer's bundle, as a number in your store's currency. Each product's price is multiplied by its quantity.
If the bundle has a bundle price, the total is the bundle price plus the products in groups charged in addition to it. Products covered by the bundle price don't add to the total.
isCovered(groupId)
Returns true if the group's products are included in the bundle price, so they have no price of their own. Returns false for groups charged in addition, and for every group when the bundle has no bundle price. Use it to decide whether to show a product's price:
const showPrice = !bundle.isCovered(group.id)
setField(groupId, property, value)
Sets the customer's answer to a custom field. property is the field's property from context. For dropdown and colour swatch fields, value is the chosen option's label. Spaces at the start and end are trimmed, and an empty value clears the answer.
Throws an error if:
- The group doesn't exist or isn't a custom fields group, or the field doesn't exist.
- The group is nested and isn't shown.
- The value isn't one of a dropdown or colour swatch field's options.
- The value is longer than a text field's character limit.
removeField(groupId, property)
Clears the customer's answer to a custom field.
missingFields()
Returns the required custom fields, in groups that are shown, that the customer hasn't answered yet. Each has a groupId, property and label. Returns an empty array when nothing is missing.
formatMoney(amount)
Formats an amount as a price using your store's money format, converted to the customer's currency. Pass an amount in your store's currency, such as the result of total().
bundle.formatMoney(bundle.total()) // "$61.20"
addToCart(options)
Adds the customer's bundle to the cart, along with their custom field answers in groups that are shown. Answers are added as line item properties, as the standard form adds them.
| Option | Type | Description |
|---|---|---|
quantity | number | How many bundles to add. Defaults to 1 |
useCartAttributes | boolean | Also add each product as a visible line item property. Defaults to false. See Use cart attributes |
onSuccess | function | Called with Shopify's cart response when the bundle is added |
onError | function | Called with the error if adding fails |
Bundle data
context has this shape:
{
"max_price": "57.60",
"min_price": "57.60",
"groups": [
{
"id": 12,
"title": "Choose 3 packs",
"position": 0,
"min": 3,
"max": 3,
"condition_group": false,
"variants": [
{
"guid": "6f1c…",
"id": "gid://shopify/ProductVariant/4455",
"product_id": "gid://shopify/Product/3344",
"label": "M8 Blend, Ground",
"price": "19.20",
"quantity": 1,
"optional": true,
"position": 0
}
]
}
]
}
| Field | Description |
|---|---|
max_price, min_price | The most and least a customer could pay for one bundle, in your store's currency |
bundle_price | The bundle's bundle price. Only present when one is set |
groups[].id | The group's ID, used with the API's methods |
groups[].title | The group's title |
groups[].position | The group's order in the bundle |
groups[].min, max | The group's minimum and maximum selections of optional products |
groups[].linked_group | The parent group's ID. Only present on nested groups |
groups[].linked_product | The guid of the parent product that shows this group. Only present on nested groups set to show for one product |
groups[].condition_group | true for condition groups |
groups[].logic[0].branches | A condition group's branches. Each has an id, a label, a position and the group it shows |
groups[].additional_price | true for groups charged in addition to the bundle price. Only present when set |
groups[].type | "fields" for custom fields groups. Only present on those groups |
groups[].fields[] | A custom fields group's fields. Each has a guid, label, property (the cart property name), type (text, select or color), help, multiline, max_length, options (each with a label, and a color for swatches), optional and position |
groups[].variants[] | The group's products |
variants[].guid | The product's ID within the bundle, used with the API's methods |
variants[].id, product_id | The Shopify variant and product IDs |
variants[].label | The product's name in the bundle |
variants[].price | The price of one unit in the bundle, in your store's currency |
variants[].quantity | How many units the customer gets |
variants[].optional | true for optional products, false for fixed products |
Groups are listed in a flat array. Use linked_group to work out which groups are nested, and isShown() to decide when to show them.
Custom fields groups have no products. Render their fields as inputs, and pass the customer's answers to setField().
Events
The standard bundle form fires events on the bundle-selection element. They bubble, so you can listen on document.
bundle-selection-changed
Fired when the customer changes their selection or quantity, and once when the form loads.
document.addEventListener('bundle-selection-changed', (event) => {
const { total, quantity, products } = event.bundleData
console.log(`${products.length} products chosen, total ${total * quantity}`)
})
event.bundleData contains:
| Field | Description |
|---|---|
total | The bundle's price for one bundle, including fixed products and any bundle price, in the customer's currency |
price | The bundle price, if there is one, plus the chosen optional products it doesn't cover, in your store's currency |
quantity | The quantity selected |
products | The chosen optional products, each as a group ID (g) and position (p) |
included | The fixed products included, each as a group ID (g) and variant ID (i) |
branches | The chosen condition branches |
bundle-selection-validated
Fired when the customer selects Add to cart and the form checks their selection.
document.addEventListener('bundle-selection-validated', (event) => {
if (!event.validated.valid) {
analytics.track('bundle_validation_failed')
}
})
event.validated contains valid (true or false) and msg, the form-level error message, if there is one.
If there's more than one bundle form on the page, check event.target to see which form fired the event.
