File a claim

Endpoint: /go/packageOpenApiWeb/OpenApiV2/ClaimReport

Submit a claim using a service order ID.

See API reference · ClaimReport for the complete schema.

Notes:

• Required fields are serviceOrderId, claimItems, and claimPaymentObj; describe is optional.
• See Claim types for claimType: 1 damaged / 2 lost / 3 delay / 4 return compensation / 5 accidental damage / 6 electrical or mechanical failure / 7 design defect.
• When claimPaymentObj=1 (buyer), accountInfo is required. accountInfo.address is one address string, not an array of strings.
• Claim items use pic, itemNum, and priceCurrency. The payment-method key in a claim-report request is paymentMethod; claim queries and callbacks use claimPaymentMethod.
• compensationReason is an optional compensation-reason code. Omit it or send 0 when unspecified. Shipping protection accepts 1–8; product protection accepts 101–104. A value outside the selected product’s range is rejected.
• Item-level claimpayout is the claim amount assessed by the merchant platform for that item. Send it as a string in the major unit of priceCurrency; the endpoint sums the item values into the requested claim amount. It is not a compensation-method field.
• Item-level claimpayoutType is deprecated and should not be sent. Use top-level paymentMethod for the payment channel in a claim-report request.
• Top-level refundId and orderGoodsId are only for integrations that have agreed to file claims from refund events. Together they form the idempotency key; idempotency is enabled only when both are provided. Ordinary integrations may omit both. The item-level orderGoodsId identifies the covered order item and has a different purpose.
• API Reference Try-it can write the last synced service-order id and item identity from Try-it settings with Fill current request. The example claim amount is fixed at 10.00.

Request example

{
    "serviceOrderId": "20250818XPP0001ABCD",
    "claimInsuranceType": 4,
    "claimType": 5,
    "compensationReason": 101,
    "fileLinks": [
        "https://example.com/file1.jpg",
        "https://example.com/file2.jpg"
    ],
    "comments": "The item was damaged in transit.",
    "claimPaymentObj": 1,
    "paymentMethod": 2,
    "accountInfo": {
        "accountName": "John Doe",
        "accountNumber": "9876543210",
        "routingNumber": "021000021",
        "address": "123 Main St, Apt 4B, New York, NY 10001, United States"
    },
    "claimItems": [
        {
            "itemId": "item-001",
            "skuId": "SKU001",
            "orderGoodsId": "orderGoodsId001",
            "itemName": "Sample protected product",
            "pic": "https://example.com/product-001.jpg",
            "priceCurrency": "USD",
            "itemNum": 1,
            "itemUnitPrice": "120.00",
            "itemSumPrice": "120.00",
            "claimpayout": "10.00"
        }
    ]
}

Response example

{
    "errCode": 0,
    "errMsg": "success",
    "data": {
        "claimId": "xmh_claim001"
    }
}