Javascript API

The JavaScript API offers a variety of functions and events that allow you to enhance bundle functionality on your store. Whether you want to extend the features of your bundles or seamlessly integrate the extension into your theme, the API gives you the flexibility to customize and optimize your setup with ease.

Building your own bundle selection component

Enable the bundle metadata element

The bundle metadata element loads in the data for a selected bundle without loading the BundleM8 selection UI. This allows you to interact with the bundle data and build your own bundle selection component.

See the theme extension settings for how to enable the element.

Initialise the Javascript API

Using the product ID you can get the API for each bundle metadata element on the page.

window.addEventListener('load', function() {
  const bundlem8Api = bundlem8(productId)
})

The bundlem8 variable is assigned to the window so if you receive a bundlem8 is undefined error then include window in your call.

const bundlem8Api = window.bundlem8(productId)

The bundleApi method accepts a second parameter to specify which bundle metadata element you want to get. This is for cases where there are more than one instance of the bundle metadata element with the same product ID on the page. The default value for this component is 1 and you specify the number based on the render order of the component within the page document.

const bundlem8Api = bundlem8.bundleApi(productId, elementPosition)

API Reference

context

The context property contains all of the bundles groups, products and conditions. This is what you will need to build out your form or component.

{
  max_price: <string>
  min_price: <string>
  groups: <array>[
    {
      id: <int>
      optional: <bool>
      single_inclusion: <bool> // Single inclusion means only one selection of an optional product is allowed
      title: <string>
      linked_group: <int> // The parent group
      variants: <array>[
        {
          id: <int> // This relates to the variant ID of the product
          label: <string>
          optional: <bool>
          position: <int> 
          price: <string>
          product_id: <string>
          quantity: <int>
        }  
      ]
    }
  ]
}

inventory

The inventory property contains data relating to the inventory levels and availability of the bundles' included products. This data is recent at the time of page-load. Additionally you'll find the original SKU, title and pricing of each product. You can use this data to extend your display, such as showing a pricing discount comparison.

<array>[
  {
    available: <bool>
    id: <int>
    policy: <string> // Will be either continue or deny. When set to continue you should allow the product to be sold.
    price: <string>
    sku: <string>
    soh: <int> // Note the value of this is redundant when tracked is set to false
    tracked: <booL>
  }
]

selected

The selected property shows all currently selected product options. Use this to display a separate list of selected options to your customers.

<array>[
  {
    groupId: <int>
    label: <string>
    position: <int>
    price: <string>
    productId: <string>
    variantId: <string>
  }  
]

config

The config property shows Shopify specific context for the theme extension.

{
  debug: <boolean>
  moneyFormat: <string>
  baseCurrency: <string>
  localeCurrency: <string>
  localePrice: <string>
  showCurrencyCode: <boolean>
}

total()

Returns the total value of all selected products. This value is represented in the users currency.

bundle.total()
// Output <float>

formatMoney()

The formatMoney() method will format a price based on the currency formatting settings set from your Shopify admin settings.

The below examples are in AUD. Note that this function will use your local currency as per your Shopify settings.

The first parameter is the value to format. This accepts a string, integer or float.

bundle.formatMoney(200)
// Output: $200

bundle.formatMoney(200.00)
// Output: $200

bundle.formatMoney("200")
// Output: $200

The second parameter determines if the value should be converted to your customers local currency. This is set to true by default.

We grab the customers local currency from the currency.iso_code property of the cart Liquid object. This will only apply if your theme is setup for currency switching.

const priceAud = 200;
bundle.formatMoney($priceAud, true)
// Output: $137.38 (USD)

$bundle.formatMoney($priceAud, false)
// Output: $200 (AUD)

selectProduct()

The selectProduct() method can be used to add a product to the selected property. It accepts two required parameters, groupId and position. Because a bundle group can contain multiple copies of the same product the guid property acts as a unique identifier.

bundle.selectProduct(groupId, optionPosition)

You would generally use this method in the callbacks for your option input event listeners.

const onChangeHandler = (event) => bundle.selectProduct(groupId, position)
input.addEventListener('change', onChangeHandler)

removeProduct()

The removeProduct() method simply removes a product from the selected property. It accepts two required parameters, groupId and position.

With the addition of the removeProduct method we would update the handler from the selectProduct example to:

const onChangeHandler = (event) => {
  event.currentTarget.checked
    ? bundle.selectProduct(groupId, position)
    : bundle.removeProduct(groupId, position)
}
input.addEventListener('change', onChangeHandler)

addIncludedProducts()

The addIncludedProducts() method can be used to add all included (non-optional) products from a bundle group to the selected property. It accepts a single paramter: groupId.

bundle.addIncludedProducts(groupId)

You should use this option when toggling the visibility of your individual groups to ensure all included products make their way to the cart.

removeIncludedProducts()

The removeIncludedProducts() method can be used to remove all included (non-optional) products within a bundle group from the selected property. It accepts a single paramter: groupId.

bundle.removeIncludedProducts(groupId)

addToCart()

To add your selected bundle options to the cart you must use the addToCart() method. This ensures the correct data is passed through to our cart functions which are responsible for correctly inserting and displaying the bundled product within the customers cart.

The addToCart() method accepts an object as it's only parameter with the following properties.

{
  quantity: <int>
  useCartAttributes: <bool>
  onSuccess: <callback>
  onError: <callback>
}

The useCartAttributes property will additionally add the selected products to the cart as line item properties. This is to cater for themes that do not support line item components. The default value of this field is false.

The onSuccess and onError callbacks receive the response that is shown on the Shopify Cart API reference.

const onSuccessHandler = (response) => {
  // Do something
}
const onErrorHandler = (error) => {
  // Alert the customer of error
}

bundle.addToCart({
  quantity: 1,
  useCartAttributes: true,
  onSuccess: onSuccessHandler,
  onError: onErrorHandler
})