Guides
Guides

Initialize the SDK and show offers

Load the browser SDK on your own site, fetch warranty offers for a product, and render them.

On a custom site you drive the Mulberry browser SDK yourself: load mulberry.js, initialize it with your public token, fetch the offers for a product, and render them inline on the page or in a modal. By the end of this page a shopper viewing an eligible product sees Mulberry coverage and can select a plan, and you have captured the warranty_offer_id you'll register at checkout.

🚧

Pass the product's price unchanged — don't convert it to cents

mulberry.core.getWarrantyOffer forwards price to Mulberry exactly as you pass it. Use the decimal price your platform already gives you (for example '2999.00') and pass it through unchanged. Don't multiply it to cents. (The cents conversion only applies to the plural batch helper, which a custom site doesn't call.)

Prerequisites

Before you start, make sure:

  • You've picked the custom path in Choose your integration — this page is for sites with no Mulberry platform adapter.
  • You have your Public Token for the environment you're building against. See Get your credentials. This is the browser-safe credential, not your server API token.
  • You can render a <script> tag and a container element on your product page, and you have the product's id, title, and price available client-side.

Steps

1. Load the SDK script

Add the SDK script to your product page. Loading it populates the window.mulberry namespaces you'll call below.

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

You should now have window.mulberry defined, with mulberry.core, mulberry.inline, and mulberry.modal available.

📘

Staging uses a different host

The script above is the production SDK. When building against staging, load it from the staging host instead and initialize with your staging public token — credentials are not interchangeable across environments (Get your credentials).

2. Initialize and await init

Call mulberry.core.init with your public token, then await mulberry.core.initCompleted. Init fetches your account's warranty settings and resolves the geo gate; nothing else works until it has resolved.

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

You should now have mulberry.core.settings populated — you'll pass it to the render call in step 4. For the full init signature and the properties it sets, see Mulberry SDK reference.

👍

Verify the token immediately

If init resolves without an authorization error, your public token is valid for that environment. A wrong or wrong-environment token fails here.

3. Fetch offers for the product

Call mulberry.core.getWarrantyOffer with the product you're showing. Pass the price exactly as your platform gives it to you.

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: productJson,  // optional; when it includes variants, the SDK resolves the SKU
})

You should now have an array of offer objects — or an empty array [] when Mulberry has no coverage for the product. (getWarrantyOffer resolves to null when the visitor's location is outside the supported region.) Branch on this: only render when offers is a non-empty array.

For the full parameter list, the offer object's fields, and the price rule, see Mulberry SDK reference. Don't re-derive them here.

4. Render the offers

Render offers either inline (inside a container on the page) or in a modal overlay. Both calls take offers and mulberry.core.settings, and both no-op when there are no offers or the location is invalid.

Inline renders into a container you select and reports selection through onWarrantyToggle:

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()
  },
})

Modal overlays the offers and reports selection through onWarrantySelect:

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()

You should now see Mulberry offers rendered for an eligible product — radio/buttons inline, or the modal once you call instance.open(). For every init parameter, the layout options, and instance methods like updateOffer (use it on a variant change), see Mulberry SDK reference.

5. Capture the selected offer

The selection callbacks are where you record the shopper's choice. Their payload shapes differ:

  • Inline — onWarrantyToggle({ offer, isSelected }) fires on both select and deselect. Read isSelected to know which.
  • Modal — onWarrantySelect(offer) receives the offer directly.

In both cases the only field you forward to your cart, checkout, or registration is offer.warranty_offer_id:

const selectedOfferId = offer.warranty_offer_id

You should now have a warranty_offer_id for the plan the customer chose. Hand it off to register the sale — see Add a warranty to an order.

🚧

Always pass a selection callback

Pass onWarrantySelect to modal.init (or onWarrantyToggle to inline.init). It's the only place the shopper's choice is reported, so without it you capture no warranty_offer_id to register. For the modal, onWarrantySelect defaults to a no-op when omitted — the selection is silently dropped. For the inline widget there is no default, so omitting onWarrantyToggle breaks on the first toggle; always pass one.

Next steps

Updated about 1 month ago