Mulberry SDK reference

This is the contract reference for the Mulberry browser SDK exposed at window.mulberry. Use it to look up exact signatures, parameters, return values, and the shape of the offer object. For end-to-end walkthroughs, see Initialize the SDK and Add a warranty to an order — those guides link here for the details.

🚧

Pass the price unchanged — don't convert it

getWarrantyOffer forwards price to Mulberry's offer API exactly as you pass it (components/shared/API/index.js:119). Use the decimal price your platform already gives you — for example Shopify's product JSON variant.price — and pass it through unchanged. Don't multiply it to cents or otherwise transform it.

Prerequisites

Before any namespace below is usable:

• The SDK script is loaded: <script src="https://app.getmulberry.com/plugin/static/js/mulberry.js"></script>
• You have called mulberry.core.init({ publicToken }) and awaited mulberry.core.initCompleted. modal, inline, and learnMore await this internally; button and faq don't, but they read core.settings / core.offers, which are only populated once init resolves — so always await init first.
• You have your public token. See Get your credentials.

Namespaces

window.mulberry exposes these partner-facing namespaces:

📘

Other namespaces are internal

The SDK also exposes subscription, enrollment, cartManager, checkout, analytics, helpers, and cta. These power Mulberry Unlimited and managed integrations and are not part of the supported partner surface — don't call them directly.

core

The entry point. Initializes the SDK against your account, fetches offers, and gates rendering by location.

core.init(props)

Initializes the SDK. Resolves core.settings, core.validLocation, and the core.initCompleted promise. Call this once, as early as possible, and await it before fetching offers.

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

Parameters (single object):

Returns: Promise resolving to the raw warranty settings. You normally await core.initCompleted rather than this return value.

Instance properties set after init:

core.getWarrantyOffer(product)

Fetches the warranty offers available for a product. Await core.initCompleted first.

const offers = await mulberry.core.getWarrantyOffer({
  id: 'OSLO-XYZ',
  title: 'Oslo Chaise in Velvet',
  price: '2999.00', // your platform's price, passed through unchanged
  detail: shopifyProductJson,
})

Parameters (single product object):

Returns: Promise<offer[]> — an array of offer objects. Resolves to [] when Mulberry has no coverage for the product. Resolves to null when core.validLocation is false (an error is logged to the console).

👍

Send warranty_offer_id at checkout

When the customer selects an offer, the only field you send to your cart, checkout, or registration call is offer.warranty_offer_id. See Add a warranty to an order.

core.getCoverageDetails(programId)

Fetches coverage details for a coverage program by id. Used by the learnMore namespace; call it directly only if you render your own "what's covered" UI.

Returns: Promise resolving to the coverage data object.

modal

Renders offers in a modal dialog overlaid on the page. Returns an instance you keep a reference to.

modal.init(config)

const instance = mulberry.modal.init({
  offers,
  settings: mulberry.core.settings,
  onWarrantySelect: (offer) => {
    addWarrantyToCart(offer.warranty_offer_id)
    mulberry.modal.close()
  },
  onWarrantyDecline: () => mulberry.modal.close(),
})
instance.open()

Parameters (single config object):

Returns: the modal instance (or false if there are no offers or the location is invalid).

Instance methods:

inline

Renders offers inline inside a container element you select. Returns an instance you keep a reference to.

inline.init(config)

const instance = mulberry.inline.init({
  offers,
  settings: mulberry.core.settings,
  selector: '#mulberry-inline',
  onWarrantyToggle: ({ offer, isSelected }) => {
    if (isSelected) addWarrantyToCart(offer.warranty_offer_id)
    else removeWarrantyFromCart()
  },
  layout: { input: 'radio' },
})

Parameters (single config object):

layout fields:

Returns: the inline instance (or false if there are no offers or the location is invalid).

Instance methods:

button

Renders a single Mulberry button into a container. Clicking it opens the offer modal (initialized from core.offers).

button.init(config)

Methods: setLoading(isLoading) toggles the button's loading state.

faq

Opens the standalone "what's covered" FAQ overlay for a single offer.

faq.init(config) / faq.open() / faq.close()

Call faq.init(config) then faq.open() to display it, and faq.close() to dismiss.

learnMore

Wires up "Learn more" triggers on the page. Each element matching .mulberry-learn-more becomes a clickable trigger that opens the FAQ overlay.

learnMore.init(config)

Each trigger element reads data-program-id and an optional data-layout ('text' by default) attribute. init no-ops if core.validLocation is false.

The offer object

getWarrantyOffer returns an array of these. The table covers the partner-relevant fields only — the response includes additional internal fields you can ignore.

📘

product vs. product_meta

offer.product is Mulberry's serialized view of the covered product, and it carries is_subscription_eligible. offer.product_meta is a copy of the exact product object you passed to getWarrantyOffer. Use whichever is more convenient.

Typical flow

1. Load the SDK script: <script src="https://app.getmulberry.com/plugin/static/js/mulberry.js"></script>.
2. await mulberry.core.init({ publicToken }), then await mulberry.core.initCompleted. You should now have mulberry.core.settings populated.
3. const offers = await mulberry.core.getWarrantyOffer(product), passing the product's price unchanged. You should now see an array of offers (or [] if there's no coverage).
4. Render with mulberry.inline.init(...) or mulberry.modal.init(...), passing offers and mulberry.core.settings.
5. On select, send offer.warranty_offer_id to your cart, checkout, or registration flow. See Add a warranty to an order.