Bundler JavaScript API Documentation


What is the Bundler JavaScript API?

JavaScript API documentation explains how to use various JavaScript events and methods in Shopify shops, which have the Bundler app installed.

When the Bundler app gets loaded

When the Bundler app gets loaded, Bundler automatically triggers the bundler:loaded event.
Here is how you can configure a listener for said event:

// This event will be fired whenever the Bundler app is loaded
    document.addEventListener('bundler:loaded', function(e) {
        // Do your magic :) 
    });

When the bundle widget gets created

When the bundle widget gets created, Bundler automatically triggers the bundler:bundle_widget_created event.
Here is how you can configure a listener for said event:

// This event will be fired whenever a bundle widget is rendered
    document.addEventListener('bundler:bundle_widget_created', function(e) {
        // e.detail will contain the following JSON object:
        // {
        // 		products: products,	// Contains products in the bundle which the bundle widget represents
        // }
    });

You can use this event to add any custom product options or metafields to the bundle. A thing to note here is that when the customers click the add to cart button in the bundle widget, the app will add products to the cart together with all line item properties that are in the .bndlr-product elements.
For example, you could add a custom line item property to the products in the bundle widget with the following code:

// This event will be fired whenever a bundle widget is rendered
    document.addEventListener('bundler:bundle_widget_created', function(e) {
        document.querySelectorAll('.bndlr-product').forEach(function(el, index) {
            el.innerHTML += '<input name="properties[custom_property]" type="hidden" value="custom property value" />';
        });
    });

When cart values are recalculated

Whenever Bundler recalculates the total cart value and if the discount is bigger that 0, then the bundler:total_cart_values event will be triggered. The cart values are recalculated on page load and after a bundle is added to the cart.
This is how the event gets triggered:

// This event will be fired when the cart values are recalculated
var event = new CustomEvent("bundler:total_cart_values", {
    detail: {
        total_amount_original    	: originalAmount,
        total_amount_discounted    	: discountedAmount,
        discount_amount            	: discountAmount,
        original_cart_object   		: originalCartData
    }
});
document.dispatchEvent(event);

This is how you can listen to this event:

document.addEventListener('bundler:total_cart_values', function(e) {
    console.log('Event details', e.detail);
    // The e.details will contain the object with the necessary info.
    // Also, a thing to note here is that the values are always in cents, not in dollars,
    // therefore you have to divide them by 100 to get dollars.
});

And this is how you can trigger the app to recalculate and update cart values (available on premium plans):

window.bndlr.updateCartDiscounts();

When product is added to the cart from the bundle widget

After the product gets added to the cart, our Bundler - Product Bundles app automatically triggers the following product:added event.
Here is how this event is triggered:

// This is how the event is triggered
document.dispatchEvent(new CustomEvent('product:added', {
    bubbles: true,
    detail: {
        variant: variantId,
        quantity: quantity
    }
}));
And here is how you can configure a listener for said event:

// This is how you can configure a listener for said event
document.addEventListener('product:added', function() {
    // Do your magic :) 
}));

When the bundle is added to the cart through the bundle widget

After all products from the bundle are added to the cart, our Bundler - Product Bundles app automatically triggers the following bndlr:bundle_added_to_cart event.
Here is how you can configure a listener for said event:

document.addEventListener('bndlr:bundle_added_to_cart', function() {
    // Do your magic :) 
});

To get the checkout link, where the discounts are already applied, you can use the getCheckoutInfo() method on window.bndlr JavaScript object. This is how you can call it:

// This is how the event is triggered
window.bndlr.getCheckoutInfo(
    function(data) {
        console.log(data);
        if (typeof data !== 'undefined' && typeof data.can_apply_discount !== 'undefined' && data.can_apply_discount === true) {
            // Do your magic with the discount
        } else {
            // Discount can't be applied
        }
        
        // Data object in this callback will contain properties
        // can_apply_discount: Boolean	<-- whether the app has any discount to apply or not
        // code: String 				<-- discount code, if applicable (the merchant must turn on the option to apply discounts with discount codes in Bundler > General Settings > Apply discounts).
        // items: Array[], 				<-- items with detailed pricing and discount info
        // status_code: Integer, 		<-- status code, 200 means OK, 201 means that the draft order is not yet ready
        // url: String 					<-- URL to which the customer would get redirected to get a discount. If a discount code is used, then it will contain a discount code, if a draft order is used then a link to the draft order will be here.
    }
);


How to force the app to render bundle widgets?

In case you added the bundle shortcode to your page after the Bundler was loaded, then you can call the window.bndlr.refresh() method:
if (typeof window.bndlr !== 'undefined' && typeof window.bndlr.refresh === 'function') {
    window.bndlr.refresh();
}

The app will check for any elements where it can render the bundle widget and render it there.

How to get the bundles configured in the app?

You can get the bundles configured in the app by calling the bndlr.getBundles() method. You can see this in the example below:

if (typeof window.bndlr !== 'undefined' && typeof window.bndlr.getBundles === 'function') {
    var bundles = window.bndlr.getBundles();
    // Do your magic with bundles :) 
}


How can I add additional parameters to the checkout?

You can add additional checkout parameters with the setCheckoutParams method:

// The parameters passed in this function will be added to the checkout URL
window.bndlr.setCheckoutParams({
    'checkout[shipping_address][first_name]': 'John'
});


How can I prevent Bundler checkout?

You can prevent Bundler from controlling the checkout by calling preventBundlerCheckout method:

// Prevent bundler from overriding your checkout logic
window.bndlr.preventBundlerCheckout();

And to re-enable the Bundler checkout, use the enableBundlerCheckout method:

// Re-enable Bundler checkout logic
window.bndlr.enableBundlerCheckout();


How can I trigger Bundler checkout?

You can trigger the Bundler checkout by calling checkout method:

// Trigger bundler checkout
window.bndlr.checkout();