Guides
Guides

Shopify Custom Integration

Suggest Edits

The Mulberry Shopify application works out of the box for standard Shopify themes, however, sometimes this isn't enough for more advanced layouts. For cases like these developers are able to access the underlying API directly.

Getting the offer information

You'll need to write some custom JavaScript to ask the Mulberry API to fetch an offer for the current product.

📘

The contents of the 'detail' node is the product json you can obtain directly from Shopify. You can easily see the contents by going to your PDP and putting .json at the end of the URL and you should see the required structures.

Add this full payload into the detail node to retrieve an offer.

Once the PDP/product page is fully loaded, you'll call the following:

const offers = await mulberry.core.getWarrantyOffer(
  {
    title: 'Oslo Chaise in Velvet',
    id: 'OSLO-XYZ',
    price: '2999.00',
    detail: {
      // The Shopify product node for the product in question
      id: 1234567890,
      title: 'Oslo Chaise in Velvet',
      product_type: "Chair",
      variants{...}
      ...
  }
)

If Mulberry can provide coverage for the product an offer will be returned. The response should look something like this:

[
  {
    "cost": "189.00",
    "coverage_details": [
      {
        "long": [
          "Stains from food/beverage and human/pet bodily fluids",
          "Rips & tears",
          "Seam separation",
          "Burn or heat marks (up to one inch in length)",
          "Breakage of frames",
          "Any electrical components"
        ],
        "short": [
          "Stains, rips & tears",
          "Seam separation",
          "Burn & heat marks",
          "Frame breakage"
        ]
      }
    ],
    "created_date": "2019-08-02 11:17:31.035565+00:00",
    "customer_cost": "189.00",
    "duration_months": "36",
    "external_product_id": null,
    "id": "179115",
    "mb_category": "seating",
    "product": {
      "name": "Smokin' Sofa in Smoked Chrome Mirror",
      "price": "2995.00",
      "retailer": {
        "company_name": "Electroshop",
        "integration": "shopify"
      }
    },
    "service_type": "Repair",
    "warranty_hash": "29e75e85d110c049c35cb72e4989e633f13e7dce74e38493ae64e4b0273ef139"
  }
]

Once we have this data, it's time to render it as an inline or modal offer or both.

Rendering the Modal

Once we've initialized Mulberry and fetched an offer, the next step involves passing the settings and offer data into the Mulberry modal.

const { settings } = mulberry.core;      

const modal = window.mulberry.modal.init({
  offers,
  settings,
  onWarrantySelect: (warranty) => {
    // handle select
  },
  onWarrantyDecline: () => {
    mulberry.modal.close()
    // additional processing...
  }
})

We are now ready to open the modal. Typically, when a customer clicks "Add to Cart" is when we want to trigger this modal, however, it can be triggered at any time. For the purposes of this document, let's assume we're going the standard "Add to cart" route.

🚧

Callbacks

Note the onWarrantySelect() and onWarrantyDecline() callbacks above. It's here where we'll need to implement code to add the product and warranty to the customers cart. See here for additional information.

It's likely that when you click "Add to cart" on your theme that either a form POST or ajax request is made. Instead of this default behavior, you'll need to instead make a call to the modal to display it.

mulberry.modal.open()

// or when referring to a specific instance
const modal = await window.mulberry.modal.init(/***/)
// ...
// ...
// ...
modal.open();

You should now see the modal displayed with the appropriate offer and branding.

Re-fetching offers when variant changes

Sometimes the price of a Shopify product changes depending on which variant the customer has selected. At times like this, you must re-fetch the offer with the updated pricing and update the front end offer components with the revised offer details. When a variant changes, the Mulberry Shopify app dispatches an event named mulberry-shopify:variant-change containing the newly selected Variant ID. You can listen to this event on the document as shown below. If you're using components from the Mulberry SDK, you can simply call the [component].updateOffer() method and the UI will be updated automatically.

document.addEventListener('mulberry-shopify:variant-change', function(e) {
  console.log('newly selected variant ID', e.detail);
  
  // fetch new offer by passing new variant price information.
  // see section "Getting the offer information above"
  const offers = await mulberry.core.getWarrantyOffer(...);
  
  mulberry.modal.updateOffer(offers);
                                                      
});

Responding to user actions

Two things can happen once a modal is displayed for the customer: they can accept or decline the offer. If a user chooses to add the warranty to their purchase, the onWarrantySelect() callback will be fired with data about the warranty. Conversely, if the user opts out of the warranty, the onWarrantyDecline() callback will be called.

Putting it all together

async function init() {
  let response = await mulberryShop.getProductData(mulberryShop.getProductUrl())
  let product = response.product;
  
  const offer = await mulberry.core.getWarrantyOffer({
    id: product.id,
    title: product.title,
    price: product.variants[0].price, // For purposes of demo only using first variant
    detail: product
  })

 await mulberry.modal.init({
    offers: offer, 
    settings: mulberry.core.settings,
    onWarrantySelect: async (warranty) => {
      const result = await mulberryShop.getWarrantyVariant(warranty);
      await mulberryShop.addWarrantyToCart(result.shopify_variant_id, product, warranty);
      mulberry.modal.close();
    },
    onWarrantyDecline: () => {
      mulberry.modal.close();
    }
  })

  // Simplified for purposes of demo. The call to mulberry.modal.open() would 
  // happen within your theme where you handle CTA click / add to cart form 
  // submission.
  const addToCartButton = document.querySelector('.add-to-cart');
  addToCartButton.addEventListener('click', async () => {
    mulberry.modal.open();
  })
}

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

Removing unused warranties from the cart

Sometimes a user will remove a product from their cart that has a warranty associated with it. You can automatically remove these "detached" warranties by calling the removeDetachedWarranty() function.

Call this function by passing the response returned by the Shopify Cart API (cart object). You should typically call this after making any changes to the contents of the customers cart. 

const cartWithoutUnusedWarranties = await mulberryShop.removeDetachedWarranty(cart);
// Update cart UI with the updated cart contents
// e.g. Shopify.onCartUpdate(cartWithoutUnusedWarranties);

🚧

Important

For mulberryShop.removeDetachedWarranty() to work you must make sure to pass the product variant ID into previous call to mulberryShop.addWarrantyToCart() as shown below.

await mulberryShop.addWarrantyToCart(31885558480975, {title: 'Blue Sofa', variantId: 23423423423});

Updated over 3 years ago