Submit claims through the API

Preview: file customer claims, add evidence, and reconcile status from your backend.

🚧

API preview — rollout pending

This 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

OperationEndpointReference
File a claimPOST /api/claimsSubmit a partner claim
Read current status and evidence metadataGET /api/claims/{claim_id}Get a partner claim
Reconcile or find a partner referenceGET /api/claimsList partner claims
Add supporting filesPOST /api/claims/{claim_id}/documentsAdd 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

  1. Find the warranty and covered item. Read GET /api/v2/orders?external_id=YOUR_ORDER_ID. Use data[].warranties[].id for warranty_issued_id and that warranty's line_items[].id for line_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_id may be omitted only when the warranty covers exactly one unit.

  2. Submit the incident details from your backend. Keep external_claim_id stable for this claim. claim_date is the incident's calendar date; optional received_at is 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 201 with data.id, replayed: false, and processing_pending. Save data.id alongside your reference. The claim enters Mulberry's existing review workflow.

    To include initial evidence, send multipart form data with a payload field containing the same JSON and one or more attachments fields:

    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.

  3. 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. Preserve received_at if you supplied it; do not replace it with the retry time.

    An accepted duplicate returns 200, replayed: true, and the same data.id, even if the claim's status has since changed. Reusing the reference with different data returns 409. Whitespace around text is trimmed; attachment order does not matter.

    If processing_pending is true, the claim is saved but background work has not all been queued. Retry the identical submission with backoff until it is false. Never invent a new reference to repair a pending submission. Escalate persistent failures to Mulberry with data.id and your reference.

    You should now have one Mulberry claim linked to one reference in your system.

  4. 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 200 returns 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.

  5. 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 include page, per_page, and total_count. The default page size is 50; the maximum is 100. Results are newest first and include claims from other filing channels, with external_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; read reason and 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

SUBMITTED acknowledges filing. PENDING_FINANCE means 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-null payout_amount alone 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.