Integrate on BigCommerce

BigCommerce is a front-end integration: you edit your Stencil theme to load the Mulberry SDK, render offers on the product page, and then attach the chosen plan to the BigCommerce cart by POSTing it to Mulberry's custom-items endpoint. The SDK mechanics are shared across every platform and live in the Mulberry SDK reference — this page covers the two BigCommerce-specific pieces: the Stencil theme edits and the cart attach call.

🚧
The cart endpoint uses snake_case top-level keys
The custom-items request body is store_hash, cart_id, custom_items — not storeHash or cartId. The backend reads the snake_case keys by direct subscript, so a camelCase key 500s the request. Read both values from BigCommerce's jsContext, not from undefined variables.

Prerequisites

Before you start, make sure:

You have your public token for mulberry.core.init. See Get your credentials. The public token is client-safe; never put your server-side API token in theme JavaScript.
You can edit your store's Stencil theme files (base.html and your product page template).
The Mulberry BigCommerce app is installed on your store, so store_hash and cart_id are available on the storefront jsContext.

📘
You don't register the sale by hand
Once the warranty is in the BigCommerce cart and the order is placed, the Mulberry app registers the sale for you. There is no manual checkout call to make from the theme.

Load the SDK

In your theme's base.html, add the SDK script to the <head>:

<script src="https://app.getmulberry.com/plugin/static/js/mulberry.js"></script>

This exposes window.mulberry. Initialize it once, as early as possible, with your public token:

await mulberry.core.init({ publicToken: 'YOUR_PUBLIC_TOKEN' });
await mulberry.core.initCompleted;

You should now have mulberry.core.settings populated. See core.init for the full parameter list.

Add the inline container

In your product page template, add an empty container where the inline offer should render:

<div class="mulberry-inline-container"></div>

Place it near your Add to Cart button — that's where customers expect to see the offer.

Fetch and render offers

After init resolves, fetch offers for the current product and render them. Read the product fields from BigCommerce's Stencil context and pass the price through unchanged — Mulberry's single-offer call does no cents conversion:

const offers = await mulberry.core.getWarrantyOffer({
  id: '{{product.sku}}',
  title: '{{product.title}}',
  price: '{{product.price.without_tax.value}}',
});

getWarrantyOffer returns an array of offer objects, or [] when Mulberry has no coverage. Render them with the inline namespace, the modal namespace, or both, and capture the selected offer.warranty_offer_id — that's the only field you attach to the cart. The full signatures, the offer object, and the inline/modal callbacks are documented in the Mulberry SDK reference; don't re-implement them here.

You should now see a Mulberry offer rendered on an eligible product page.

📘
Mulberry Unlimited (post-purchase)
If you sell Mulberry Unlimited subscriptions, the order-success enrollment widget is documented separately. See Mulberry Unlimited on BigCommerce.

Attach the warranty to the cart

This is the BigCommerce-specific step. When the customer selects an offer, POST it to Mulberry's custom-items endpoint, which adds it to the BigCommerce cart as a custom item:

POST https://mb-shim.getmulberry.com/api/bigcommerce/carts/custom-items

The endpoint is unauthenticated from the storefront — send only Content-Type: application/json, no auth header. Mulberry looks up the store by store_hash and injects the merchant's BigCommerce token server-side.

Body field	Type	Description
`store_hash`	string	The store hash, from `jsContext.storeHash`.
`cart_id`	string	The active cart id, from `jsContext.cartId`.
`custom_items`	array	One item per warranty to add (see below).

Each custom_items entry follows BigCommerce's v3 custom-items schema:

Item field	Type	Description
`sku`	string	The offer's `warranty_offer_id`. This is the value Mulberry reads to match the plan.
`name`	string	A display label for the line item, e.g. `"Mulberry Protection"`.
`list_price`	number	The customer-facing plan price — `offer.customer_cost`.
`quantity`	integer	Number of plans to add.

On success the endpoint passes BigCommerce's v3 cart object back through unchanged. On failure it returns HTTP 500 with { "error": "Unable to add custom cart items." }.

🚧
sku is the offer id, list_price is the plan price
Send offer.warranty_offer_id as sku and offer.customer_cost as list_price — not the underlying product's id or price. customer_cost is what the customer pays for the plan; the product's price is the price of the item being covered.

End-to-end example

Drop this into your product page template (it assumes jQuery and the Stencil jsContext). It loads the SDK, fetches offers, renders inline and modal, and attaches the selected plan to the cart:

const jsContext = JSON.parse('{{jsContext}}');

async function addWarrantyToCart(offer, quantity = 1) {
  const apiUrl = 'https://mb-shim.getmulberry.com/api/bigcommerce/carts/custom-items';
  return fetch(apiUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      store_hash: jsContext.storeHash,
      cart_id: jsContext.cartId,
      custom_items: [
        {
          sku: offer.warranty_offer_id,
          name: 'Mulberry Protection',
          list_price: offer.customer_cost,
          quantity: quantity,
        },
      ],
    }),
  });
}

async function mulberryInit() {
  await mulberry.core.init({ publicToken: 'YOUR_PUBLIC_TOKEN' });
  await mulberry.core.initCompleted;

  const offers = await mulberry.core.getWarrantyOffer({
    id: '{{product.sku}}',
    title: '{{product.title}}',
    price: '{{product.price.without_tax.value}}',
  });

  if (!offers || offers.length === 0) {
    return;
  }

  let selectedOffer = null;

  // Inline offer next to Add to Cart.
  window.pdpInline = mulberry.inline.init({
    offers: offers,
    settings: mulberry.core.settings,
    selector: '.mulberry-inline-container',
    onWarrantyToggle: ({ offer, isSelected }) => {
      selectedOffer = isSelected ? offer : null;
    },
  });

  // Modal fallback when nothing is selected inline.
  window.pdpModal = mulberry.modal.init({
    offers: offers,
    settings: mulberry.core.settings,
    onWarrantySelect: async (offer) => {
      await addWarrantyToCart(offer);
      mulberry.modal.close();
      // Navigate to the cart page or refresh your cart slideout here.
    },
    onWarrantyDecline: () => {
      mulberry.modal.close();
      // Navigate to the cart page or refresh your cart slideout here.
    },
  });

  // Intercept Add to Cart: attach the inline selection, or prompt with the modal.
  $("form[action='/cart/add']").submit(async (event) => {
    if (selectedOffer) {
      await addWarrantyToCart(selectedOffer);
      // Refresh your cart slideout here if you have one.
    } else {
      event.preventDefault();
      window.pdpModal.open();
    }
  });
}

$(document).ready(() => {
  mulberryInit();
});

👍
Verify it end to end
Open an eligible product page, select the offer, and add the product to the cart. You should now see the Mulberry plan as a line item in the BigCommerce cart at the customer-facing price, and the order should register with Mulberry automatically once it's placed.

Next steps

Mulberry SDK reference — full signatures for core, inline, and modal, the offer object, and the price-pass-through rule.
Get your credentials — find your public and API tokens.
Mulberry Unlimited on BigCommerce — add the post-purchase subscription enrollment widget.

The cart endpoint uses snake_case top-level keys

Prerequisites

You don't register the sale by hand

Load the SDK

Add the inline container

Fetch and render offers

Mulberry Unlimited (post-purchase)

Attach the warranty to the cart

sku is the offer id, list_price is the plan price

End-to-end example

Verify it end to end

Next steps

`sku` is the offer id, `list_price` is the plan price