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

  1. In the theme editor, add the Bundle Selection block to your bundle product template.
  2. Turn on Metadata only in the block's Advanced settings.
  3. 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)
ParameterTypeDescription
productIdnumber or stringThe bundle product's numeric ID, such as {{ product.id }} in Liquid
indexnumberOptional. 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:

  1. 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.
  2. 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.ready waits 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

PropertyTypeDescription
idstringThe bundle product's ID
readyPromise<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
contextobjectThe bundle's groups, products, price range and bundle price. Always the latest data. See Bundle data
inventoryarrayStock information for every variant in the bundle
selectedarrayThe products currently in the customer's bundle
branchesarrayThe condition branches the customer has chosen
fieldsarrayThe custom field answers that will be added to the cart, each with a property and value. Leaves out answers in groups that are hidden
configobjectThe 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.

OptionTypeDescription
quantitynumberHow many bundles to add. Defaults to 1
useCartAttributesbooleanAlso add each product as a visible line item property. Defaults to false. See Use cart attributes
onSuccessfunctionCalled with Shopify's cart response when the bundle is added
onErrorfunctionCalled 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
        }
      ]
    }
  ]
}
FieldDescription
max_price, min_priceThe most and least a customer could pay for one bundle, in your store's currency
bundle_priceThe bundle's bundle price. Only present when one is set
groups[].idThe group's ID, used with the API's methods
groups[].titleThe group's title
groups[].positionThe group's order in the bundle
groups[].min, maxThe group's minimum and maximum selections of optional products
groups[].linked_groupThe parent group's ID. Only present on nested groups
groups[].linked_productThe guid of the parent product that shows this group. Only present on nested groups set to show for one product
groups[].condition_grouptrue for condition groups
groups[].logic[0].branchesA condition group's branches. Each has an id, a label, a position and the group it shows
groups[].additional_pricetrue 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[].guidThe product's ID within the bundle, used with the API's methods
variants[].id, product_idThe Shopify variant and product IDs
variants[].labelThe product's name in the bundle
variants[].priceThe price of one unit in the bundle, in your store's currency
variants[].quantityHow many units the customer gets
variants[].optionaltrue 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:

FieldDescription
totalThe bundle's price for one bundle, including fixed products and any bundle price, in the customer's currency
priceThe bundle price, if there is one, plus the chosen optional products it doesn't cover, in your store's currency
quantityThe quantity selected
productsThe chosen optional products, each as a group ID (g) and position (p)
includedThe fixed products included, each as a group ID (g) and variant ID (i)
branchesThe 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.

Previous
Styling with CSS