Add the warranty to the order

On a custom integration, this is the bridge between showing an offer and registering the sale: when the customer selects a Mulberry offer, capture its warranty_offer_id and carry that ID through your own cart and order so it's available when you call checkout.

There is no Mulberry cart helper to do this for you. Unlike the Shopify app — which writes the warranty into the Shopify cart automatically — a custom integration owns its cart and order model, so you are responsible for storing warranty_offer_id alongside the product the customer is buying and forwarding it at checkout.

🚧

warranty_offer_id is the only field you carry forward

From the selected offer object, offer.warranty_offer_id is the single value you store and later send to register the sale. Don't reconstruct the offer from price or title — those don't identify the plan. Keep the ID intact (it's an opaque string) and don't transform it.

Prerequisites

Before you start, make sure:

• You've completed Initialize the SDK — the SDK is loaded, mulberry.core.init({ publicToken }) has been awaited, and you're rendering offers with mulberry.inline.init or mulberry.modal.init.
• You have an offers array back from mulberry.core.getWarrantyOffer(product) for the product on the page.
• Your cart or order representation can hold an extra field per line — somewhere to keep warranty_offer_id next to the product the customer is buying.

Capture the selection

You don't poll for the selection — the render namespace calls a callback you provide. Wire your "add to cart" logic into that callback. The callback differs by how you rendered the offers:

• Inline offers call onWarrantyToggle({ offer, isSelected }) — it fires on both select and deselect, so handle the isSelected flag.
• Modal offers call onWarrantySelect(offer) on add, and the optional onWarrantyDecline() on close.

For the full callback signatures and config, see the Mulberry SDK reference.

Inline

1. In inline.init, set onWarrantyToggle to add or remove the warranty in your cart based on isSelected:

   JavaScript

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

2. Select an offer on the page. Your addWarrantyToCart runs and warranty_offer_id lands in your cart. Deselect it, and removeWarrantyFromCart runs.

You should now see the warranty_offer_id stored in your cart whenever an offer is selected, and cleared whenever it's deselected.

Modal

1. In modal.init, set onWarrantySelect to add the warranty to your cart, then close the modal:

   JavaScript

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

2. Open the modal and add coverage. Your addWarrantyToCart runs with the selected offer's warranty_offer_id, and the modal closes.

You should now see the warranty_offer_id stored in your cart for that order.

🚧

Always pass your selection callback

The modal callbacks (onWarrantySelect, onWarrantyDecline) default to a no-op when omitted, so a missing callback just silently drops the selection. Inline is stricter: onWarrantyToggle has no default, so if you omit it the first select or deselect throws an error. Either way the SDK has no cart of its own to write to — passing the callback is what makes a custom integration work.

Carry the ID through your order

Store warranty_offer_id against the product line it covers, and keep it attached as the customer moves from cart to order. How you persist it is entirely yours — a field on the cart line, an entry in session state, a column on the order — but it must survive to the moment you register the sale.

🚧

Tie the warranty to the product it covers

Keep warranty_offer_id associated with the specific product (and variant) the customer is buying. At registration you send both the product and its warranty_offer_id together, so a warranty that's lost track of its product can't be registered.

When the customer changes the variant or product, the offers change too. Re-fetch with mulberry.core.getWarrantyOffer(product), refresh what's rendered with the instance's updateOffer(offers), and clear any previously captured warranty_offer_id so you don't carry a stale plan to checkout. See the Mulberry SDK reference for the instance methods.

👍

You've captured the warranty

With warranty_offer_id stored on the order, you're ready to register the sale. Send it to Mulberry's checkout endpoint in Register the sale.