Cainiao tracking API

Empower your dev team with seamless Cainiao tracking using Track123’s API.

Effortlessly set up real-time Cainiao tracking through a robust RESTful API and webhooks, automating delivery updates as they happen. With a Track123 account, enjoy rapid tracking updates and an industry-leading 99.9% API uptime. Take your logistics to the next level with the Cainiao Tracking API from Track123.

Cainiao Tracking API

Register trackings

Parameters

RAW_BODY
array of objects
An array of objects where each object contains the following details:
- trackNo
  string
  Track number
- courierCode
  string
  The unique carrier code, if it is null, the system will auto-detect carrier base tracking number format
- orderNo
  string
  Order number
- country
  string
  Country code of destination: CN,US,GB
- shipTime
  string
  Ship time
- customerEmail
  string
  The customer email address associated with the order
- postalCode
  string
  The postcode of the destination (15 letters or numbers, can contain +, -, and spaces)
- extendFieldMap
  object
  Be used to add additional information, such as phone number
- remark
  string
  Remark
- custom1
  string
  Custom field 1
- custom2
  string
  Custom field 2

Returns

code
string
Service status code
data
object
- accepted
  array of objects
  Successful registration of tracking number
- rejected
  array of objects
  Rejected registration of tracking number
msg
string
The description information corresponding to the service status code or other auxiliary description information.
traceId
string

shell

curl --request POST \
   --url https://api.track123.com/gateway/open-api/tk/v2/track/import \
   --header 'Track123-Api-Secret: Test' \
   --header 'accept: application/json' \
   --header 'content-type: application/json' \
   --data '[
            {
              "trackNo": "LV209031969CN",
              "courierCode": "cainiao",
              "orderNo": "x1234567890",
              "country": "CN",
              "shipTime": "2024-01-01 12:00:00",
              "customerEmail": "customer@track123.com",
              "postalCode": "000000",
              "extendFieldMap": {
                "phoneSuffix": "2390"
              },
              "remark": "remark",
              "custom1": "customField1",
              "custom2": "customField2"
            }
    ]'

response.json

  {
    "code": "00000",
    "data": {
      "accepted": [
        {
          "trackNo": "LV209031969CN",
          "courierCode": "cainiao",
          "postalCode": "000000",
          "orderNo": "x1234567890",
          "country": "CN",
          "shipTime": "2024-01-01 12:00:00",
          "customerEmail": "customer@track123.com",
          "remark": "remark",
          "extendFieldMap": {
            "phoneSuffix": "2390"
          }
        }
      ],
      "rejected": [
        {
          "index": 2,
          "trackNo": "LV209031969CN",
          "orderNo": "x1234567890",
          "courierCode": "cainiao",
          "error": {
            "code": "A0400",
            "msg": "The order number has been imported"
          }
        }
      ]
    },
    "msg": "Success",
    "traceId": "79160aef7dde4df3ab53d77a5e783fad.161.17086538800398087"
  }

Get trackings

You can track up to 100 tracking numbers at a time.