Guides
Guides

Custom integration overview

Build offers and sale registration yourself with the Mulberry SDK and REST API — no platform app required.

This is the entry page for the custom integration path — the one you take when your storefront isn't on a supported platform (Shopify, Magento, BigCommerce, WooCommerce) and there's no Mulberry app doing the wiring for you. You'll do two things yourself that a platform app would otherwise handle: fetch and display warranty offers with the browser SDK, and register each warranty sale with one server-to-server REST call. Claims, cancellations, and refunds then run through Mulberry's cross-cutting flows, the same as every other path.

🚧

Two tokens, two jobs — don't mix them up

The custom path uses two distinct credentials. The public token initializes the browser SDK (mulberry.core.init({ publicToken })) and is safe to ship in client-side code. The API token authenticates your server's sale-registration call (Authorization: Bearer <api-token>) and must stay server-side. Sending one where the other is expected returns 401 Unauthorized. See Get your credentials.

What you're building

Three pieces make up a working custom integration:

  1. Show offers (browser, SDK). Load the SDK, initialize it with your public token, fetch offers for the product the customer is viewing, and render them inline or in a modal. When the customer selects a plan, you capture one field: offer.warranty_offer_id.
  2. Register the sale (server, REST). When the order is placed, your server POSTs the order — including the selected warranty_offer_id — to POST /api/checkout. This is the step a platform app would do for you. It's what actually creates the warranty contract in Mulberry.
  3. Handle the lifecycle (cross-cutting). Claims, replacements, cancellations, and refunds aren't path-specific. Once a sale is registered, you use the same cross-cutting flows as everyone else — see Claims, Cancel a warranty, and How refunds work.
📘

Why register the sale yourself?

On a supported platform, the Mulberry app listens for the order and registers the warranty automatically. The custom path has no app in that position, so your server makes the registration call. Everything downstream of registration is identical to the platform paths.

Shipping insurance is available on this path too, with the same shape: the SDK quotes and renders the offer, your server registers the policy. See Add shipping insurance.

Prerequisites

Before you start, make sure:

  • You have a Mulberry account with a signed partner agreement.
  • You have your public token and API token for the environment you're building against. See Get your credentials.
  • You've confirmed the custom path is right for you — if you're on a supported platform, use that integration instead. See Choose your integration.
  • You understand the offer → cart → register flow at a high level. See How Mulberry works.

The spine

Showing offers and registering sales lean on two contracts that are documented once, in the reference tier — don't reimplement them from scratch:

  • The browser SDK (window.mulberry) fetches and renders offers. For exact signatures, the offer object, and the callbacks, use the Mulberry SDK reference.
  • The REST API registers the sale. The custom-path walkthrough is in Register the sale.
🚧

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

When you fetch offers with mulberry.core.getWarrantyOffer(product), pass the decimal price your platform already uses (for example "2999.00") exactly as-is. The singular getWarrantyOffer forwards price straight to Mulberry's offer API with no conversion. Multiplying it to cents will price the offer wrong. This is the single most common custom-path mistake. The full contract is in the SDK reference.

Follow the path in order

Each page below ends where the next one begins. Work through them in sequence:

  1. Get your credentials — collect your public token and API token for the right environment.
  2. Initialize the SDK — load mulberry.js, call mulberry.core.init({ publicToken }), and fetch offers for a product.
  3. Add a warranty to an order — render the offers, capture the customer's selection, and carry offer.warranty_offer_id into your cart.
  4. Register the sale — POST the completed order with its warranty_offer_id to POST /api/checkout to create the warranty contract.
  5. Test and go live — verify against staging, then swap in your production credentials and cut over.
👍

Ready to start

If your credentials are in hand, head straight to Initialize the SDK. Otherwise, get them first at Get your credentials.

After registration

Once a sale is registered, the warranty is live and the rest of its lifecycle runs through Mulberry's cross-cutting flows — not through this path:

Updated 14 days ago