File a claim

A claim is how a covered customer asks Mulberry to make good on a warranty. In almost every integration you do not file claims yourself — your customers file directly with Mulberry, and Mulberry adjudicates and settles the claim with nothing built on your side. This page explains both how customers file and the narrower, gated path where an enabled retailer files on a customer's behalf.

📘

You don't need to file claims to be integrated

The default, fully-supported path is that customers file directly with Mulberry and Mulberry handles the rest. If you want claim status mirrored in your own records, that's the optional CLAIM_UPDATE webhook, set up on request — see React to claim updates. Filing on a customer's behalf is an opt-in feature in limited rollout (see Filing on a customer's behalf below).

For the full claim lifecycle — statuses, outcomes, and how a claim resolves — see How claims work.

The customer path (default)

For most integrations, this is the only path that applies to you.

A customer with an active Mulberry warranty files a claim directly through Mulberry — there is nothing for you to build or call. They reach the claim flow from their confirmation email, the policy terms, or Mulberry's customer experience (CX) team, and they provide the details and any supporting photos. You don't host this flow and you don't proxy it.

Once the claim is created, Mulberry takes over adjudication:

1. The claim is created and lands in SUBMITTED.
2. Mulberry reviews and resolves the claim, and its status changes as it goes — UNDER_REVIEW, APPROVED or DENIED, RESOLVED, CLOSED.

If Mulberry has set up the optional CLAIM_UPDATE webhook for you, each status change, starting with SUBMITTED, is posted to your claim_update_url and correlated to your order by order.external_order_id. See React to claim updates.

❗

A system-closed claim still sends a CLAIM_UPDATE

When a cancellation closes an open claim, Mulberry still sends a CLAIM_UPDATE — with status CLOSED and reason CLOSED_CANCELLED_BY_CUSTOMER. Handle a CLOSED status the same way whether a human or the system triggered it. Which cancellations close claims — a transaction cancellation does; a plain order cancellation does not — is covered in Cancel a warranty.

📘

Handle only the partner-facing statuses

The values you'll see on CLAIM_UPDATE are SUBMITTED, UNDER_REVIEW, APPROVED, DENIED, RESOLVED, and CLOSED. Other internal statuses exist; treat any value you don't recognize as a forward-compatible addition, not an error. The full list and the resolution outcomes (reason, payout_amount, issued_replacement) are documented in How claims work.

Filing on a customer's behalf

Some retailers can file a claim for a customer — for example, when a shopper reports an issue in-store or by phone instead of going through Mulberry's CX flow. This is a partner-dashboard feature, not a public REST endpoint, and it is not generally available.

🚧

Retailer-filed claims are gated and not self-serve

Filing claims on a customer's behalf is enabled per retailer and is off by default. There is no public, token-authenticated API for it — it runs inside the authenticated partner dashboard, scoped so a retailer can only file for warranties on its own orders. Don't build against it as a stable, self-serve capability. If you want it turned on for your account, contact your Mulberry representative or Partner Success.

When this feature is enabled for your account, an authorized dashboard user (a partner admin or limited partner role) files the claim against the customer's Mulberry warranty from within the dashboard. A claim filed this way enters the same lifecycle as a customer-filed one and emits the same CLAIM_UPDATE webhooks if you receive them — so nothing on your side changes based on who filed.

📘

Identify the warranty, not the order

A claim is filed against a specific Mulberry warranty, not an order ID. If you're coordinating a filing with Partner Success, have the warranty's Mulberry identifier (from the ORDER_SUCCESS webhook or the dashboard) ready, along with the claim date and a description of the issue.

Service line items (retailer-managed repair)

Beyond simply opening a claim, an enabled retailer can attach service line items — itemized repair work priced against Mulberry's repair catalog — when filing on a customer's behalf. This is the retailer-managed repair flow.

This flow is in limited pilot, narrower still than basic retailer filing:

• Each line item is chosen from Mulberry's repair catalog (Mulberry derives the description and pricing from the catalog entry, not from values you type).
• A claim filed without service line items follows the standard customer/CX flow and lands in SUBMITTED.
• A claim filed with service line items may need Mulberry to review the priced items before it advances, depending on the line items and your account's configuration.

🚧

Repair-catalog filing is a single-retailer pilot

The service-line-item / repair-catalog flow is a V1 pilot, not a general partner feature, and its rollout and behavior are subject to change. Don't document or depend on it as part of your standard integration. If repair-catalog filing is on your roadmap, raise it with Partner Success — and ask them where general availability stands.

📘

Line-item adjudication is Mulberry's

Pricing, approval thresholds, and per-line-item review are internal to Mulberry. As a partner you file the items; Mulberry decides how they're approved and what the payout is. If you receive CLAIM_UPDATE, the outcome arrives there like any other claim outcome.

What you receive either way

No matter who files, claim activity reaches your systems only through the optional CLAIM_UPDATE webhook — there's no polling API. Mulberry sets it up on request. It fires on every status change, including the final resolution, so ask for it if you mirror claim status in your own records.

Its payload shape, headers, HMAC-SHA256 signing, and retry behavior are documented once in the Webhook catalog — verify every request before acting on it.

Next steps

• How claims work — the full lifecycle, statuses, and resolution outcomes.
• React to claim updates — handling the CLAIM_UPDATE webhook.
• Webhook catalog — payloads, signing, and retries for every event.