How claims work
The claim lifecycle from a partner's point of view — who files, how Mulberry adjudicates, and why there's nothing for you to build.
A claim is a customer's request for service on a warranty you sold them — a repair, a replacement, a cash settlement, or a care kit. This page explains the claim lifecycle so you know what Mulberry handles and where your integration fits. The short version: claims need nothing built on your side. Customers file with Mulberry, and Mulberry adjudicates and settles every claim. You don't approve, price, deny, or pay out anything.
The claim webhook is optionalDeciding a claim (repair vs. replacement vs. cash, payout amounts, denials) is Mulberry's responsibility, not yours, and so is settling it. If you want claim status in your own systems, Mulberry can send a
CLAIM_UPDATEwebhook, but it's off unless you ask for it — see What the partner does.
What a claim is
When something goes wrong with a covered product, the customer opens a claim against the warranty contract that was created when you registered the sale. Each claim is tied to one warranty (and therefore one product and one order), carries a status as it moves through review, and ends in either an approval with a specific outcome or a denial.
If you've asked for it, Mulberry reports claim activity to your systems through the CLAIM_UPDATE webhook. It fires on any claim status change, so you can mirror the lifecycle in your own records. It's documented in full — payload, headers, signing, and retries — in the Webhook catalog.
Who files a claim
Claims are filed directly with Mulberry by the customer, through the Mulberry customer portal or with help from Mulberry Partner Success. This requires nothing from you — the customer never touches your systems to open a claim.
There is no claim-filing APIDon't build a customer-facing "file a claim" button that posts to a Mulberry endpoint — there isn't one. Point customers at the Mulberry portal; if a customer needs help, route them to Mulberry support or your Partner Success contact.
How Mulberry adjudicates
Once a claim is opened, Mulberry takes it through review. From a partner's perspective the lifecycle is a small, stable set of statuses — the same subset the webhook carries:
| Status | What it means for you |
|---|---|
SUBMITTED | The claim has been filed and is queued for review. No action needed. |
UNDER_REVIEW | Mulberry is adjudicating. No action needed. |
APPROVED | Mulberry approved the claim with a specific outcome (see Resolution outcomes). |
DENIED | Mulberry denied the claim. No action needed. |
RESOLVED | The approved outcome has been carried out and the claim is settled. |
CLOSED | The claim is closed — manually, or automatically (for example, when the underlying order is cancelled). |
Treat unknown statuses as forward-compatibleThe six statuses above are the partner-facing set, but the
statusfield can carry other values over time. Branch only on the statuses you handle and ignore the rest rather than erroring — see the field notes in the Webhook catalog. Mulberry uses additional internal statuses during review; they are deliberately not part of the partner contract.
An auto-closed claim still sendsCLAIM_UPDATEWhen a claim is closed automatically because its underlying order was cancelled, it lands in status
CLOSEDwith reasonCLOSED_CANCELLED_BY_CUSTOMER— and if you receiveCLAIM_UPDATE, Mulberry still delivers one for the transition. Handle aCLOSEDstatus the same way whether a human or the system triggered it. See Cancel a warranty.
Resolution outcomes
When Mulberry approves a claim, it resolves to one of a few outcomes. Mulberry decides which one and how much it's worth — you don't choose or price it. At a partner-relevant altitude, the outcomes are:
- Repair or cleaning — the product is serviced rather than replaced.
- Replacement — a replacement unit is issued. Mulberry's claims team handles it; there's nothing for you to do.
- Cash settlement — the customer is paid out. The amount appears as
payout_amounton theCLAIM_UPDATE. - Stain or care kit — a kit is sent to the customer.
The webhook surfaces the specific outcome as an opaque reason string on the CLAIM_UPDATE (for example, a replacement carries a FINANCE_APPROVED_REPLACEMENT-style reason). Treat reason as an informational label, not a value to hard-code branching logic against — branch on status, and read issued_replacement to tell whether a replacement was issued.
What the partner does
Nothing, by default. Mulberry reviews, decides, prices, and settles every claim, and Mulberry's claims team handles replacements. There's no claim endpoint to build, and claims aren't part of going live.
If you mirror claim status in your own records, ask your Mulberry representative to set up the optional CLAIM_UPDATE webhook. Mulberry then posts each status change to your claim_update_url, and you match events to claims by data.claim.id. See React to claim updates.
There's no payout or settlement webhook to wait onMulberry settles claim payouts server-side; there is no partner-facing settlement webhook and no endpoint for you to call to compute or trigger a payout. (Cancellation refunds aren't Mulberry's to send either — those run through your store; see How refunds work.)
Related
- React to claim updates — handling
CLAIM_UPDATE - Webhook catalog — the
CLAIM_UPDATEpayload, headers, signing, and retries - Cancel a warranty — how cancellations auto-close claims
Updated 12 days ago