Sync platform order

Endpoint: /go/packageOpenApiWeb/OpenApiV2/SyncPlatformOrder

Synchronize an e-commerce order to Xcotton. Call the endpoint again when the order changes. A simple integration first synchronizes the order before payment and then sends later payment and status updates. Xcotton determines whether to activate coverage from the order state.

Shipment data can be included here or sent through the shipment synchronization endpoint.

See API reference · SyncPlatformOrder for the complete schema.

Notes:

• orderInfo.receiverInfo is required here; only CalcPrice allows it to be omitted.
• orderInfo.itemList is required here. Without item lines the policy stores no item details and later claims cannot be filed; warranty lines must also carry ppVariant.
• For automatic activation of a paid order, payTime and paySn are required and orderState must be PAIED or a later state.
• Use the exact historical literals UNPAIED, PAIED, UNSHIPED, SHIPED, DELIVERED, and FINISHED; do not correct their spelling. See Order states.
• The JSON keys ItemPicInfoMain and Properties use PascalCase. Product-protection plan data belongs in ppVariant.properties.
• An item purchasing product protection must include item-level insuredPayPrice, a valid ppVariant.price, and ppVariant.properties. Use the real Plan ID returned by the quote endpoint. When protection was not purchased, omit ppVariant or send null; do not send an empty object {}.
• Read the result from data.orderId, xmhShopOrderId, insurance.spInsureDetail.serviceOrderId, and insurance.ppInsureDetail.insureItemList.
• After a successful sync, Try-it settings show the service-order id under Last sync for the claim fill button. The order and shipment examples share the same orderId. Fill current request does not rewrite the body.

Request example

{
    "userId": "customer-005",
    "userEmail": "customer@example.com",
    "orderInfo": {
        "orderId": "order-005",
        "currency": "USD",
         "totalPrice": "201.00",
        "preferentialPrice": "10.00",
        "taxPrice": "0.00",
         "shipPrice": "0.00",
         "totalPayPrice": "191.00",
         "insuredPayPrice": "0.00",
         "insuredPayPriceForExtended": "1.00",
         "payTime": "2025-08-18T15:37:22+08:00",
         "paySn": "pay-005",
         "itemList": [
             {
                 "itemId": "item-001",
                 "skuId": "SKU001",
                 "orderGoodsId": "orderGoodsId001",
                 "itemName": "Sample protected product",
                 "ItemPicInfoMain": [
                     "https://example.com/product-001.jpg"
                 ],
                 "currency": "USD",
                 "unitNum": "1",
                 "unitPrice": "120.00",
                 "preferentialPrice": "5.00",
                 "totalPrice": "120.00",
                 "totalPayPrice": "115.00",
                 "insuredPayPrice": "1.00",
                 "Properties": {},
                 "ppVariant": {
                     "variantId": "pp-variant-1y",
                     "name": "1 Year",
                     "price": "1.00",
                     "currency": "USD",
                     "currencySymbol": "$",
                     "properties": {
                         "Reference": "item-001",
                         "Plan ID": "1 Year",
                         "Product": "Sample protected product"
                     }
                 }
             },
             {
                 "itemId": "item-002",
                 "skuId": "SKU002",
                 "orderGoodsId": "orderGoodsId002",
                 "itemName": "Sample product without protection",
                 "ItemPicInfoMain": [
                     "https://example.com/product-002.jpg"
                 ],
                 "currency": "USD",
                 "unitNum": "1",
                 "unitPrice": "80.00",
                 "preferentialPrice": "5.00",
                 "totalPrice": "80.00",
                 "totalPayPrice": "75.00",
                 "Properties": {}
             }
         ],
         "receiverInfo": {
             "receiverShipAddress": {
                 "country": "United States",
                 "countryCode": "US",
                 "province": "California",
                 "provinceCode": "CA",
                 "city": "Los Angeles",
                 "postalCode": "90001",
                 "address": "125 Main Street",
                 "mobile": "+1-202-555-0100",
                 "linkName": "Jessy Doe"
             }
         },
         "orderState": "PAIED",
         "orderCreateTime": "2025-08-18T15:30:00+08:00",
         "orderModifyTime": "2025-08-18T15:37:22+08:00"
     },
     "disRcId": "xrc-example-005",
     "disComputeId": "xcp-example-005",
     "buyerIp": "192.0.2.10"
 }

Response example

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "orderId": "order-005",
    "xmhShopOrderId": "9372657428",
    "insurance": {
      "spInsureDetail": {
        "serviceOrderId": ""
      },
      "ppInsureDetail": {
        "insureItemList": [
          {
            "itemId": "item-001",
            "skuId": "SKU001",
            "orderGoodsId": "orderGoodsId001",
            "itemName": "Sample protected product",
            "currency": "USD",
            "unitNum": "1",
            "insuredPayPrice": "1.00",
            "Properties": {
              "Reference": "item-001",
              "Plan ID": "1 Year",
              "Product": "Sample protected product"
            },
            "serviceOrderIds": [
              "20250818XPP0001ABCD"
            ]
          }
        ]
      }
    }
  }
}