How Mulberry works

Every Mulberry integration — whether you install a platform app or build against the SDK and API directly — moves a shopper through the same seven stages. This page is the map. By the end you'll be able to name each stage, point to the artifact it produces (the offer you fetch, the line item in the cart, the contract that gets created, the webhook that fires), and know which page to open when you build or debug that stage.

📘

The one thing to internalize

The sale isn't real to Mulberry until you register it. A shopper can see an offer, pick a plan, and add it to the cart — but no warranty contract exists, no welcome email goes out, and no claim can ever be filed until your integration tells Mulberry the order was placed. Platform apps do this for you automatically. Custom integrations must do it explicitly. If registration is the only stage you get right, the customer is covered; if it's the only one you get wrong, they are not.

Prerequisites

This page is conceptual — there's nothing to install. To follow the links into the build steps, you should have:

• A Mulberry partner account. See Welcome to Mulberry.
• Decided, or be deciding, between a platform app and a custom build. See Choose your integration.
• A working vocabulary of terms like offer, warranty contract, and claim. See Concepts and key terms.

The integration spine

These seven stages run in order for a single shopper, from landing on a product page to a claim or refund months later:

connect → offer → present → attach → register → service → settle

The first five happen around a single purchase. The last two are the long tail: they can fire days or years after the sale and never stop being your integration's responsibility.

👍

Platform apps automate most of the spine

If you install the Shopify, Magento, BigCommerce, or WooCommerce app, stages offer → present → attach → register run for you with no code — including the registration that creates the contract. You manage configuration and watch the dashboard; the app handles the mechanics. A custom integration does these stages by hand against the SDK and API, which is why the Custom guides walk each one explicitly.

1. Connect

You establish trust between your storefront and Mulberry. A platform app does this when you install it and authenticate; a custom build does it by initializing the SDK with your public token.

What you can observe: the app shows as installed and connected in your store admin, or the SDK initializes without an auth error and returns your warranty settings.

Build it: Install the Shopify app · Initialize the SDK · Get your credentials

2. Offer

For the product a shopper is viewing, Mulberry decides whether it's eligible for coverage and, if so, returns the available protection plans. Under the hood this is the SDK's getWarrantyOffer call (or its REST equivalent): you pass the product, Mulberry's classification and pricing engine responds. Each returned offer carries its price (customer_cost), term (duration_months), and an identifier (warranty_offer_id) you'll need again at registration.

What you can observe: a response containing one or more offer objects for an eligible product, or an empty result for a product Mulberry doesn't cover.

Deep dive → Mulberry SDK reference

3. Present

The offers from the previous stage get rendered where the shopper can act on them — inline on the product page, in a modal, or at checkout. The SDK ships widgets that draw these for you; a custom build can use those widgets or render the offer data itself.

What you can observe: an offer widget appears on an eligible product's page or in the checkout flow, showing the plan options and prices.

Build it: Offers on product pages · Offers at checkout

4. Attach

The shopper selects a plan, and you add it to the cart as a line item — carrying the offer's warranty_offer_id so the selection survives to checkout. Most integrations store that identifier as line-item metadata precisely so it's available at the next stage.

What you can observe: a warranty line item in the cart alongside the product it protects, priced at the plan's customer_cost.

Build it: Add a warranty to an order

5. Register

This is the load-bearing stage. When the order is placed, your integration registers the sale with Mulberry — passing each warranty line item's warranty_offer_id. Registration is what creates the warranty contract — it turns a line item the shopper paid for into an actual policy. Mulberry sends the customer a welcome email with portal access, and the warranty becomes claimable.

What you can observe: the warranty appears in the Mulberry dashboard, the customer receives a welcome email, and your Order Success webhook fires with the warranty and order details.

🚧

This is where custom integrations fail silently

Skipping or misfiring registration produces no error in the shopper's checkout — they're charged for protection and walk away believing they're covered. The gap only surfaces later, when they try to file a claim and no contract exists. Confirm registration end to end before you go live, and treat the Order Success webhook as your proof the contract was created.

Build it: Register the sale · Test and go live

6. Service

After the contract exists, the customer can file claims against it — for a repair, a replacement, or a payout, depending on the plan. Claims move through a defined lifecycle (submitted → under review → approved → resolved, or denied/closed if the claim doesn't qualify), and your integration can react to each transition. If a plan covers replacements, fulfilling that replacement is your side of the loop.

What you can observe: a claim against the warranty, progressing through its lifecycle, with a Claim Events webhook firing on each status change.

Deep dive → How claims work · React to claim updates

7. Settle

The financial long tail. A warranty can be cancelled — by the customer or because the underlying order was returned — and the customer's refund flows back through your store's own refund process. Separately, Mulberry settles what you owe or are owed for the protection you've sold.

What you can observe: a cancelled warranty, a Warranty Updates webhook reflecting the change, and the reconciliation on your billing.

Deep dive → Cancel a warranty · How refunds work · Billing

Where the work actually lives

The spine is the same for everyone; what differs is how much of it you write.

Service and settle look the same in both columns: even a fully automated platform integration consumes the post-sale webhooks to keep your own systems in sync. See the Webhook catalog for every event and its payload.

Next steps

• Not sure which column you're in? → Choose your integration
• Building custom? Start at the top of the spine → Initialize the SDK
• On Shopify? → Install the Shopify app
• Fuzzy on a term used above? → Concepts and key terms