Submit claims through the API
Preview: file customer claims, add evidence, and reconcile status from your backend.
API preview — rollout pendingThis contract is published for integration planning. The new claims endpoints are not yet deployed. Before testing, confirm availability and partner-claims enablement with Mulberry for your staging or production account.
Use the partner claims API to send a customer's incident details to Mulberry for review. Mulberry must enable partner claims for your account before you call these endpoints. A successful submission acknowledges receipt; it does not approve a claim or authorize a payment.
Prerequisites
- Partner claims are enabled for your retailer in the environment you are using.
- Your backend has your private retailer token. Never put it in a browser or mobile client. See Get your credentials.
- The customer's sale has been registered, with an issued Mulberry warranty and covered item.
- Your system has a stable claim reference that you will reuse for every retry.
Use https://partner-staging.getmulberry.com for staging and https://partner.getmulberry.com for production. Credentials and enablement are separate for each environment.
Endpoints
| Operation | Endpoint | Reference |
|---|---|---|
| File a claim | POST /api/claims | Submit a partner claim |
| Read current status and evidence metadata | GET /api/claims/{claim_id} | Get a partner claim |
| Reconcile or find a partner reference | GET /api/claims | List partner claims |
| Add supporting files | POST /api/claims/{claim_id}/documents | Add claim evidence |
Every operation uses Authorization: Bearer YOUR_PRIVATE_TOKEN and is scoped to your retailer's visible orders. Unknown and inaccessible records return 404.
File and track a claim
-
Find the warranty and covered item. Read
GET /api/v2/orders?external_id=YOUR_ORDER_ID. Usedata[].warranties[].idforwarranty_issued_idand that warranty'sline_items[].idforline_item_id.You should now have a specific warranty and covered unit. These are public identifiers, not internal database IDs, product IDs, or SKUs.
line_item_idmay be omitted only when the warranty covers exactly one unit. -
Submit the incident details from your backend. Keep
external_claim_idstable for this claim.claim_dateis the incident's calendar date; optionalreceived_atis when your system originally received the report, with a timezone. If omitted, Mulberry records its receipt time. Replace the sample identifiers and dates before calling:curl --request POST "$MULBERRY_BASE_URL/api/claims" \ --header "Authorization: Bearer $MULBERRY_PRIVATE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "external_claim_id": "route-claim-123", "warranty_issued_id": "YOUR_WARRANTY_ID", "line_item_id": "YOUR_LINE_ITEM_ID", "claim_date": "2026-11-16", "description": "The clasp broke during normal use.", "received_at": "2026-11-16T14:20:00Z" }'A new claim returns
201withdata.id,replayed: false, andprocessing_pending. Savedata.idalongside your reference. The claim enters Mulberry's existing review workflow.To include initial evidence, send multipart form data with a
payloadfield containing the same JSON and one or moreattachmentsfields:curl --request POST "$MULBERRY_BASE_URL/api/claims" \ --header "Authorization: Bearer $MULBERRY_PRIVATE_TOKEN" \ --form-string "payload=$(cat claim.json)" \ --form "[email protected]" \ --form "[email protected]"The claim and initial evidence are saved together. A failed initial upload does not leave a submitted claim without that evidence.
-
Handle retries without opening another claim. After a timeout or a temporary
503, resend the same normalized JSON and the same initial filenames and file contents, with backoff. Preservereceived_atif you supplied it; do not replace it with the retry time.An accepted duplicate returns
200,replayed: true, and the samedata.id, even if the claim's status has since changed. Reusing the reference with different data returns409. Whitespace around text is trimmed; attachment order does not matter.If
processing_pendingistrue, the claim is saved but background work has not all been queued. Retry the identical submission with backoff until it isfalse. Never invent a new reference to repair a pending submission. Escalate persistent failures to Mulberry withdata.idand your reference.You should now have one Mulberry claim linked to one reference in your system.
-
Add later evidence when needed. Use the returned claim ID:
curl --request POST "$MULBERRY_BASE_URL/api/claims/$CLAIM_ID/documents" \ --header "Authorization: Bearer $MULBERRY_PRIVATE_TOKEN" \ --form "[email protected]"A
200returns document IDs, filenames, and file types. Repeating the same filename and bytes reuses the document ID. All files in one request are saved together. Uploads add evidence; they do not change the claim decision. -
Reconcile the claim's current state. Retrieve the claim, or recover it by your reference if the original response was lost:
curl "$MULBERRY_BASE_URL/api/claims/$CLAIM_ID" \ --header "Authorization: Bearer $MULBERRY_PRIVATE_TOKEN" curl --get "$MULBERRY_BASE_URL/api/claims" \ --header "Authorization: Bearer $MULBERRY_PRIVATE_TOKEN" \ --data-urlencode "external_claim_id=route-claim-123"You should see the claim's raw
status,reason,payout_amount, currency, identifiers, and evidence metadata. List responses includepage,per_page, andtotal_count. The default page size is 50; the maximum is 100. Results are newest first and include claims from other filing channels, withexternal_claim_id: null. Incomplete and abandoned drafts are excluded. Deduplicate by claim ID when paging while new claims arrive.
Limits and error handling
- At most 10 nonempty attachments per request. Each needs a filename with an extension.
- The entire request, including multipart overhead, must be at most 10 MiB.
- Submit incident details and evidence only. Fields such as
status,payout_amount, and service catalog line items are not accepted. 400: correct invalid fields, query parameters, or files.413: reduce request size.401/403: check the private token, environment, retailer activation, and partner-claims enablement.404: verify the warranty, covered item, or claim belongs to your retailer and is visible.409: check whether the reference was reused with different input or the warranty is no longer claimable.422: the covered item cannot take a new claim; readreasonand the returned details.503: retry the same request with backoff. This can occur during concurrent submission or temporary evidence-storage failure.
Status updates and settlement
Use the optional, signed CLAIM_UPDATE webhook for ongoing updates, and the read endpoints for reconciliation. Match data.claim.id in the webhook to data.id from this API. Your external claim reference is stored by the API; it is not added to the existing webhook payload. See React to claim updates for verification and delivery handling.
Receipt is not approval
SUBMITTEDacknowledges filing.PENDING_FINANCEmeans finance processing is pending; do not treat it as final approval or as a payment instruction. Preserve unfamiliar statuses and reconcile them without assuming approval. A non-nullpayout_amountalone does not authorize payment.
These endpoints do not calculate, initiate, or acknowledge partner payouts. Follow the settlement arrangement agreed with Mulberry separately. Claim status and evidence retrieval return no customer contact details, internal notes, or file download URLs.
Updated about 6 hours ago