Skip to content
Xcotton Xcotton Developer Docs
Ctrl K

Callback: claim sync

This endpoint is implemented by the merchant platform (webhook). The domain and path are defined and provided by the merchant platform.

Xcotton pushes claim results to the merchant. Header xmh-hmc-signature. Success is HTTP 200 only (see authentication §4.2). The body errCode is not parsed.

For the full field reference see API reference · webhook claimUpdated. Do not send requests to the OpenAPI hosts.

Notes:

  • The payment-method JSON key is claimPaymentMethod (only the claim-report request uses paymentMethod).
  • Top-level amounts claimApplyMoney / claimMoney / claimServiceFee are strings in the currency’s major unit; this differs from ClaimQuery, whose top-level amounts use the smallest currency unit.
  • Item-level claimpayoutType is not part of the current contract; ignore it if a legacy payload still includes it. The compensation method is the claim-level claimCompensationType.
  • For backward compatibility, item-level orderGoodsId currently has the same value as skuId and is not the real order-line ID. New integrations should use skuId.
  • This webhook keeps the legacy YYYY-MM-DD HH:mm:ss format for claimPaymentTime, claimGenTime, and claimTime; ClaimQuery uses RFC 3339 for comparable timestamps.
  • See Claim types for claimType / claimInsuranceType.
  • When claimType = 3 (delay compensation) or source = auto_delay, the callback additionally carries the Delay auto-compensation extension fields (source / trackingNumber / carrierCode / carrierName / promisedDeliveryTime / actualDeliveryTime / delayDays / delayTier / points / giftCardUsd / autoCompensationTaskId). Design draft — final fields are subject to engineering confirmation.

Request example:

Section titled “Request example:”
{
    "orderId": "1234567890",
    "claimId": "CL2024010100001",
    "claimType": 1,
    "fileLinks": [
        "https://example.com/file1.jpg"
    ],
    "comments": "Product damaged, claiming.",
    "claimPaymentObj": 1,
    "claimPaymentMethod": 1,
    "claimInsuranceType": 3,
    "claimItems": [
        {
            "itemId": "001",
            "productId": "p001",
            "skuId": "ABC123",
            "orderGoodsId": "ABC123",
            "variantId": "V001",
            "itemName": "Product 1",
            "pic": "https://example.com/item1.jpg",
            "itemNum": 2,
            "claimType": 1,
            "claimState": 2
        }
    ],
    "claimApplyMoney": "5000.00",
    "claimMoney": "4500.00",
    "claimMoneyCurrency": "USD",
    "claimServiceFee": "50.00",
    "claimServiceFeeCurrency": "USD",
    "claimPaymentState": 2,
    "claimPaymentTime": "2026-01-02 15:04:05",
    "claimPayTransactionNo": "TXN123",
    "claimCompensationType": 1,
    "claimReviewState": 1,
    "claimState": 3,
    "claimGenTime": "2026-01-02 15:04:05",
    "claimTime": "2026-01-02 15:04:05"
}

Delay auto-compensation example (claimType=3, design draft):

Section titled “Delay auto-compensation example (claimType=3, design draft):”
{
    "orderId": "1234567890",
    "claimId": "CL2024010100002",
    "claimType": 3,
    "claimInsuranceType": 3,
    "claimState": 3,
    "source": "auto_delay",
    "trackingNumber": "RR123456789CN",
    "carrierCode": 3011,
    "carrierName": "China Post",
    "promisedDeliveryTime": "2026-08-10T23:59:59Z",
    "actualDeliveryTime": "2026-08-15T08:30:00Z",
    "delayDays": 5,
    "delayTier": {
        "minDelayDays": 4,
        "maxDelayDays": 7,
        "method": "CASH",
        "amountUsd": "5.00"
    },
    "compensationMethod": "CASH",
    "claimMoney": "5.00",
    "claimMoneyCurrency": "USD",
    "autoCompensationTaskId": "DELAY_TASK_202608170001"
}