Guides

Shopify Cart Integrations

Suggest Edits

Mulberry makes integrating with your Shopify cart easy by taking care of all of the heavy lifting for you. By using our mulberryShop.cart API, you'll be able to get up and running with a cart integration quickly, regardless of what type of theme you have or how your cart operates (i.e. drawer/flyout, POST vs AJAX etc).

Initializing the Mulberry Cart API

The first step is to initialize the Cart API. We can do this by including the following code in the <HEAD> of your theme:

document.addEventListener('mulberry-shopify:loaded', () => {
	mulberryShop.cart.init();
});

📘

Note

If using radio-button layouts for the cart placements you can specify to have the buttons default to collapsed state to take up less vertical space. This can be done by using the layout config like so:

await mulberryShop.cart.init({layout: {collapsed: true}})

📘

Note

If using the standard cart button for the cart placements you can specify to remove the logo from the button. This can be done by using the layout config like so:

await mulberryShop.cart.init({layout: {ctaLogo: false}})

to disable the logo on the button CTA

await mulberryShop.cart.init({layout: {warrantyLogo: false}})

to disable the logo on the warranty after being added to cart.

🚧

Race Conditions

We recommend keeping this code in the <HEAD> to avoid potential "race conditions". You'll be guaranteed to catch the Mulberry event this way.

Add Mulberry Data Attributes to your Line Item Template

Depending on how your theme is structured, the method by which you implement this step may vary, however, most themes follow a similar pattern. Begin by locating the template (i.e. Liquid file) which is responsible for rendering a line item within the cart.

You'll probably notice that this particular template is looping over the line items in your cart and writing some HTML to the page. Add the data-variant-id to the outer most element of the line item. Make sure to pass the line items id as its value. This will allow Mulberry to identify the line items and manage the protection plans associated with them.

{% for item in cart.items %}
<div class="cart item" data-variant-id="{{ item.id }}">
	<div class="title">{{ item.title }}</div>
 	<div class="price">{{ item.price }}</div>
</div>
{% endfor %}

🚧

Just a Simplified Example

The markup you see above is a simplified representation of what the HTML for a line item might look like. It will look a bit different in your theme.

Hide Protection Plan Line Items

The preferred UX pattern of the Mulberry Cart API is to nest protection plans within each line item. Because of this, we need to initially hide all protection plans from being shown in the cart. Let's update the HTML we made above with the following:

<div {% if item.properties._product %} style="display: none;"{% endif %} class="cart item" data-mulberry-variant-id="{{ item.id }}">
	<div class="title">{{ item.title }}</div>
 	<div class="price">{{ item.price }}</div>
</div>

Insert the Warranty Details component

The Mulberry Warranty Details component will automatically display either an "Add Protection" button or the protection plan details, or nothing depending on whether the line item is eligible for coverage, already has coverage associated with it or cannot be covered. Add it to your HTML as shown below:

<div {% if item.properties._product %} style="display: none;"{% endif %} class="cart item" data-mulberry-variant-id="{{ item.id }}">
	<div class="title">{{ item.title }}</div>
 	<div class="price">{{ item.price }}</div>
  
	<!-- The warranty offer CTA or details will automatically show here-->
	<warranty-details data-variant-id="{{ item.id }}"></warranty-details> 
</div>

Rendering the Cart

You will need to tell Mulberry to render your cart after your HTML is rendered and any time the HTML changes afterwards (i.e. when a new product is added). You can do this by calling the mulberryShop.cart.render() function. Most themes have a function which render the line items HTML to the page. It usually makes sense to place the following directly after that function runs.

If cart contents hasn't been changed

mulberryShop.cart.render();

If cart contents has been updated

// Passing the optional refresh param will tell
// Mulberry to fetch new offers for new products
mulberryShop.cart.render({refresh: true});

Responding to Warranty Additions

Mulberry triggers a JavaScript event (mulberry-shopify:warranty-add) whenever a customer opts in to a protection plan. You must listen to this event within your theme and call your function to rebuild your cart when this happens.

document.addEventListener('mulberry-shopify:warranty-added', () => {
  myBuildCartFunction();
});

Updated 5 months ago