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 you simply react to the resulting CLAIM_UPDATE webhooks as the claim moves through its lifecycle. 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 you receive CLAIM_UPDATE webhooks. If all you need is to keep your records in sync, you don't have to file anything — skip to 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 and you start receiving webhooks:

1. The claim is created and lands in SUBMITTED.

   You receive a CLAIM_UPDATE webhook with status SUBMITTED, correlated to your order by order.external_order_id.

2. Mulberry reviews and resolves the claim. Every status change — UNDER_REVIEW, APPROVED, DENIED, RESOLVED, CLOSED — fires another CLAIM_UPDATE.

   You react to each event to keep your own records in sync. 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 — so your integration code does not change 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. You learn the outcome the same way you learn any claim outcome — through CLAIM_UPDATE.

What you receive either way

No matter who files, the claim's progress reaches you through webhooks, not a polling API:

• CLAIM_UPDATE fires on every status change, including the final resolution. This is your source of truth for where a claim stands.
• CLAIM_REPLACEMENT fires separately when a claim is marked for a replacement unit you need to fulfill.

Payload shapes, headers, HMAC-SHA256 signing, and retry behavior for both events 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.