Guides
Guides

How claims work

The claim lifecycle from a partner's point of view — who files, how Mulberry adjudicates, and what you do.

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: Mulberry runs adjudication end to end. You don't approve, price, or deny claims. Your job is to react to the lifecycle events Mulberry sends and, when a claim resolves to a replacement, to fulfill it.

📘

You don't adjudicate — you react

Deciding a claim (repair vs. replacement vs. cash, payout amounts, denials) is Mulberry's responsibility, not yours. The only adjudication-time action available to a partner is filing the claim itself, and even that is usually the customer's job. Everything else you do is downstream of Mulberry's decision, driven by the CLAIM_UPDATE and CLAIM_REPLACEMENT webhooks.

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.

Mulberry surfaces a claim to your integration through two webhooks:

  • CLAIM_UPDATE — fires on any claim status change, so you can mirror the lifecycle in your own records.
  • CLAIM_REPLACEMENT — fires only when a claim is resolved as a replacement, so you can fulfill a replacement unit.

Both are documented in full — payloads, 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 API

Don'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:

StatusWhat it means for you
SUBMITTEDThe claim has been filed and is queued for review. No action needed.
UNDER_REVIEWMulberry is adjudicating. No action needed.
APPROVEDMulberry approved the claim with a specific outcome (see Resolution outcomes). If the outcome is a replacement, a CLAIM_REPLACEMENT follows.
DENIEDMulberry denied the claim. No fulfillment action.
RESOLVEDThe approved outcome has been carried out and the claim is settled.
CLOSEDThe claim is closed — manually, or automatically (for example, when the underlying order is cancelled).
📘

Treat unknown statuses as forward-compatible

The six statuses above are the partner-facing set, but the status field 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 sends CLAIM_UPDATE

When a claim is closed automatically because its underlying order was cancelled, it lands in status CLOSED with reason CLOSED_CANCELLED_BY_CUSTOMER — and Mulberry still delivers a CLAIM_UPDATE for the transition. Handle a CLOSED status 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. This is the one outcome that asks something of you: Mulberry sends CLAIM_REPLACEMENT so you can fulfill the unit. See the Webhook catalog.
  • Cash settlement — the customer is paid out. The amount appears as payout_amount on the CLAIM_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 — the authoritative signal that you must ship a unit is the CLAIM_REPLACEMENT event, not the reason text.

What the partner does

For adjudication itself: nothing. Mulberry reviews, decides, prices, and settles every claim. Your integration's job is to stay in sync and fulfill replacements:

  1. Mirror the lifecycle. Listen for CLAIM_UPDATE and update your own records on each status change. Match events to claims by data.claim.id. See React to claim updates.

    You should now keep an accurate local view of each claim's status.

  2. Fulfill replacements. When a claim resolves to a replacement, Mulberry sends CLAIM_REPLACEMENT to your warranty_claim_url. Ship the unit and acknowledge with the exact body {"replacement_ok": true} — a bare 2xx is treated as a failure and retried. The full contract is in the Webhook catalog.

    You should now have the replacement routed to fulfillment and the delivery acknowledged.

👍

There's no payout or settlement webhook to wait on

Mulberry 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

Updated 13 days ago