Concepts and key terms

This page defines the terms that show up across every Mulberry integration, so the rest of the docs read cleanly. Skim it once, then come back when a term trips you up.

The single thing to get straight first: the token you use depends on where your code runs. Browser code uses a public token; server code uses an access token; the external-partner API uses OAuth client credentials. Mix them up and you get a 401 Unauthorized with no further detail. The Tokens and credentials section below maps each one to exactly one context.

📘

You don't provision any of these yourself

Public tokens, access tokens, OAuth client credentials, and your retailer ID are all issued by Mulberry — through Partner Success or your dashboard at dashboard.getmulberry.com. There is no self-serve signup. See Get your credentials.

Products and coverage

Offer

An offer is the protection plan Mulberry presents to a shopper before they buy — the "Add protection" widget on a product page, at checkout, or post-purchase. An offer is a quote: a price and a term for a specific product, with nothing committed yet. The SDK fetches offers in the browser and renders them. Offers carry no obligation; a shopper who ignores the widget simply leaves without one.

Warranty

A warranty is the coverage a customer actually purchased — an offer that was accepted and paid for. Where an offer is a quote, a warranty is the thing that exists in your order and in Mulberry's system, tied to the product, the customer, a cost, and a coverage term. When you "register a sale," you are telling Mulberry that a warranty was sold so it can be activated. See Register the sale.

Contract

Contract is the customer-facing word for the same purchased coverage: the legal agreement between the customer and the insurer that a warranty represents. Partners rarely touch contracts directly — you work with offers (pre-sale) and warranties (post-sale); "contract" is what shows up in customer emails and policy documents. Treat warranty and contract as the same underlying coverage seen from two angles: yours and the customer's.

👍

Quick mental model

Offer = a quote you show. Warranty = a quote that got bought and registered. Contract = that warranty as the customer sees it. One product can have many offers shown but, once sold, one warranty.

The claim lifecycle

When something goes wrong with a covered product, the customer files a claim against their warranty. Mulberry adjudicates it. As an integrator you mostly observe claim status — via webhooks or the Claims API — and, when a claim resolves as a replacement, you may be asked to fulfill it.

At a glance, a claim moves through these stages:

1. Submitted — the customer has filed the claim. It is in the queue but not yet being worked. You should now see the claim appear with a submitted status.
2. Under review — Mulberry is adjudicating: validating the warranty, the damage, and the limit of liability. No action is needed from you here.
3. Approved or Denied — the decision. An approved claim has a payout or remedy attached; a denied claim closes with a reason. You should now see the status move to one of these two terminal-ish states.
4. Resolved — the remedy has been delivered (payout disbursed, repair done, or replacement fulfilled) and the claim is complete.

The replacement branch. Some claims are approved for a replacement rather than a cash payout — and a subset of those (for example, the chatbot replacement flow) are auto-approved the moment they qualify, skipping manual review. When that happens, the claim is approved automatically and a replacement is owed. If the replacement is yours to ship, the CLAIM_REPLACEMENT webhook is your cue to act — see the Webhook catalog.

🚧

The four stages above are the partner-facing summary, not the raw status enum

Internally WarrantyClaimStatus has more values than these four — including UNDER_REVIEW, APPROVED_AUTOMATIC (the auto-approved replacement branch), REOPENED, CLOSED, and several finance/pending states such as PENDING_FINANCE. Build your webhook and polling logic against the exact status strings in the Claims reference and webhook catalog, not against the friendly names on this page. Do not assume the list is closed — handle unknown statuses gracefully.

Tokens and credentials

Every credential below is issued by Mulberry and is environment-specific: a staging token never works against production, and vice versa. Walk through obtaining each in Get your credentials.

Public token

Your public token authenticates the SDK running in the shopper's browser. You pass it when you initialize the SDK, and the SDK sends it as Authorization: Bearer <publicToken> on its requests:

mulberry.core.init({ publicToken: '<your-public-token>' })

Because it ships to the browser, the public token is not a secret — it can only fetch offers and related public data, never act on a warranty or read account data. See Initialize the SDK.

Access token

Your access token authenticates server-to-server calls to the Mulberry REST API — registering sales, cancelling warranties, and similar write operations. It is sent the same way over the wire:

Authorization: Bearer <your-access-token>

Unlike the public token, the access token is a secret: keep it on your server, never in client code or version control. See the SDK and REST reference.

Partner OAuth (client credentials)

The external-partner API uses OAuth instead of a static token. You exchange a client_id and client_secret for a short-lived bearer token using the client_credentials grant — it is the only grant type supported. POST the credentials as form-encoded data to the /external/oauth/authorize endpoint:

POST /external/oauth/authorize
grant_type=client_credentials&client_id=<id>&client_secret=<secret>

You get back a bearer access_token that expires (currently after 4 hours), so refresh it on a schedule rather than caching it forever. Keep the client_secret server-side. See Get your credentials.

Retailer ID

Your retailer ID identifies your account inside Mulberry. It is not an authentication credential on its own — it scopes data and configuration to your store and travels alongside your tokens in many calls. One retailer ID maps to one Mulberry account.

📘

Which credential, where

Credential	Where it runs	How it's sent
Public token	Browser (SDK)	Authorization: Bearer
Access token	Your server (REST)	Authorization: Bearer
Partner OAuth	Your server (external-partner API)	client_credentials → bearer
Retailer ID	Identifies the account	not an auth credential

Environments

Mulberry runs two fully separate environments: staging for building and testing, and production for live customers. They have different endpoints and different tokens — credentials are never shared across them.

• Staging is where you integrate and test. Offers, sales, and claims here are not real and bill nothing. The SDK targets staging when you initialize it in staging mode (isStaging: true).
• Production is live. Real customers, real coverage, real billing.

🚧

Don't ship staging credentials to production

Because staging and production tokens are distinct, the most common go-live bug is leaving a staging public token or access token in place when you flip to production. Audit every token at launch. Walk through it in Test and go live.

Next steps

• New here? Start with How Mulberry works.
• Ready to build? Choose your integration, then Get your credentials.
• Going deeper on claims? How claims work.