Query claims by order

Query claims by order

Endpoint: /go/packageOpenApiWeb/OpenApiV2/ClaimQueryByOrder

Query shipping-protection claims by the merchant order ID or front-end order ID.

This endpoint currently supports shipping protection only. Product protection cannot yet be queried by order; do not send claimInsuranceType=4.

• Provide at least one of orderId and frontOrderId; the field names are not longOrderNo or shortOrderNo.
• For claimInsuranceType, 3 means shipping protection. Sending 0 or omitting the field also defaults to shipping protection. Value 4 (product protection) is not currently supported.
• A typical integration calls this endpoint when the synchronized policy’s claim state is no longer 0.

See API reference · ClaimQueryByOrder for the complete schema.

Notes:

• claimMoney is a string in the currency’s major unit, for example "99.99"; do not model it as a floating-point number.
• The compensation method is the claim-level compensationMethod (1–7). Do not use the deprecated item-level claimpayoutType.
• When claimType = 3 (delay compensation) or source = auto_delay, the claim 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 examples

By merchant order ID

{
    "orderId": "order-202506010001",
    "claimInsuranceType": 3
}

By front-end order ID

{
    "frontOrderId": "XM202506010001",
    "claimInsuranceType": 3
}

Response example

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "orderId": "order-202506010001",
    "frontOrderId": "XM202506010001",
    "claims": [
      {
        "claimType": 1,
        "claimTypeDesc": "Damaged",
        "claimState": 3,
        "claimStateDesc": "Paid",
        "compensationMethod": 2,
        "compensationMethodDesc": "Full item-price compensation",
        "claimApplyTime": "2025-06-02T14:00:00+08:00",
        "claimFinishTime": "2025-06-05T10:00:00+08:00",
        "claimMoney": "99.99",
        "claimMoneyCurrency": "USD",
        "comments": "The package and item were damaged in transit.",
        "compensationExtension": {
          "placeConsumerOrders": {
            "reissueOrderNo": "reissueOrderNo-100086"
          }
        }
      }
    ]
  }
}