# Cainiao Tracking API & MCP

URL: https://docs.lastscanned.com/carriers/cainiao

Query live **Cainiao Smart Logistics** (`cainiao`, 菜鸟网络 / AliExpress Standard Shipping) cross-border package status, consolidated shipment mappings, and **domestic last-mile tracking numbers** in a single synchronous `GET` request or MCP tool call. `lastscanned` auto-detects `LP…` and `AP…` tracking numbers and returns a normalized `TrackingResult` JSON payload.

## Overview & Quick Facts

| Property | Value |
|---|---|
| **Carrier slug (`?carrier=`)** | `cainiao` |
| **Brand & service aliases** | Cainiao Smart Logistics (菜鸟), Global Cainiao, AliExpress Standard Shipping, AliExpress Selection Standard (`LP…`, `AP…`) |
| **Category** | Global cross-border e-commerce logistics network (Detection precedence **#17 of 31**) |
| **Single-package REST endpoint** | `GET https://api.lastscanned.com/v1/track/{trackingNumber}` |
| **Batch REST endpoint** | `GET https://api.lastscanned.com/v1/track?numbers=LP...,AP...` (up to 35 numbers per carrier in a 100-number call) |
| **MCP server (`https://mcp.lastscanned.com`)** | `track_package`, `track_packages`, `list_carriers` (`claude mcp add --transport http lastscanned https://mcp.lastscanned.com`) |
| **Authentication & pricing** | `Authorization: Bearer lsk_live_...` · **1 free keyless lookup/day per IP** · **Free tier** (5 unique numbers/day, $0) · **Pro** ($4.99/mo for 1,000 unique numbers, unlimited re-polls, $0.015/extra) · **HTTP 402 Stripe MPP** ($0.50 for 25-number `lsk_pack_` key or $0.02/number in USDC on Tempo) |

## Why developers use `lastscanned` for Cainiao

- **Fixes Cainiao's Beijing-time epoch bug**: Like 4PX, Cainiao's `detailList[].time` epoch interprets the local `timeStr` as `UTC+8` regardless of the scan's actual `timeZone` (`GMT-7`, `GMT+2`, etc.). `lastscanned` computes true UTC `timestamp` values directly from `timeStr` + `timeZone` so destination-country scans have accurate UTC timestamps.
- **Unpacks last-mile handoffs & consolidated AliExpress parcels**: Cainiao frequently consolidates multiple AliExpress orders into a combined bag (`mailNo`) or hands the parcel to a local last-mile carrier (`realMailNo` / `copyRealMailNo`). `lastscanned` surfaces the exchange number directly in `message`.

## Tracking Number Formats & Auto-Detection (`matches` vs `mayMatch`)

Cainiao is evaluated **seventeenth (#17)** in `lastscanned`'s two-pass detector:

| Pass | Rule / Regex | Check Digit | Examples |
|---|---|---|---|
| **Pass 1 (`matches`) — `LP` prefix** | `/^LP\d{14,17}$/i` (`LP` + 14–17 digits = 16–19 chars) | — | `LP00718293048172`, `LP00123456789012345` |
| **Pass 1 (`matches`) — `AP` prefix** | `/^AP\d{14}$/i` (`AP` + 14 digits = 16 chars) | — | `AP00830954074290` |
| **Pass 2 (`mayMatch`)** | *None* | — | — |

### When is `?carrier=cainiao` optional vs required?

- **Optional (auto-detected)**: All `LP` + 14–17 digit and `AP` + 14 digit Cainiao waybills auto-detect in Pass 1 (before AxleHire's 16-character alphanumeric rule in Pass 2).
- **Required (`?carrier=cainiao`)**: AliExpress Standard Shipping parcels assigned a `CNUSUP…` barcode, a UPU S10 number ending in `SG` / `NL` / `CN`, or a domestic last-mile barcode (`GFUS…`, `926129…`) when you specifically want Cainiao's cross-border scan history alongside the domestic handoff.

## Synchronous `GET` Request & Normalized JSON Response

### `curl`

```bash
curl -s "https://api.lastscanned.com/v1/track/AP00830954074290" \
  -H "Authorization: Bearer $LASTSCANNED_API_KEY"
```

### JavaScript / TypeScript (`fetch`)

```ts
const res = await fetch("https://api.lastscanned.com/v1/track/AP00830954074290", {
  headers: { Authorization: `Bearer ${process.env.LASTSCANNED_API_KEY}` },
});
const pkg = await res.json();
console.log(pkg.status, pkg.message, pkg.deliveredAt);
```

### MCP `track_package` tool call

```json
{
  "tool": "track_package",
  "arguments": {
    "tracking_number": "AP00830954074290"
  }
}
```

### Normalized `TrackingResult` JSON response

```json
{
  "carrier": "cainiao",
  "trackingNumber": "AP00830954074290",
  "status": "delivered",
  "statusDescription": "Package delivered",
  "service": null,
  "deliveredAt": "2026-10-24T20:15:00Z",
  "deliveredAtLocal": "2026-10-24T13:15:00",
  "signedBy": null,
  "destination": {
    "city": null,
    "state": null,
    "country": "United States"
  },
  "estimatedDelivery": null,
  "message": "Handed to the destination carrier as UUS5BM1269395824723",
  "events": [
    {
      "timestamp": "2026-10-24T20:15:00Z",
      "localTime": "2026-10-24T13:15:00",
      "status": "delivered",
      "description": "Package delivered",
      "location": null,
      "code": "DELIVERED"
    },
    {
      "timestamp": "2026-10-24T14:30:00Z",
      "localTime": "2026-10-24T07:30:00",
      "status": "out_for_delivery",
      "description": "Out for delivery",
      "location": null,
      "code": "DELIVERING"
    },
    {
      "timestamp": "2026-10-21T09:10:00Z",
      "localTime": "2026-10-21T17:10:00",
      "status": "in_transit",
      "description": "Leaving from departure country/region",
      "location": "Hangzhou, China",
      "code": "LH_DEPART"
    },
    {
      "timestamp": "2026-10-19T04:05:00Z",
      "localTime": "2026-10-19T12:05:00",
      "status": "in_transit",
      "description": "Received by logistics company",
      "location": "Shenzhen, China",
      "code": "SC_INBOUND_SUCCESS"
    }
  ]
}
```

> **Raw status & action codes**: `events[].code` preserves Cainiao's `actionCode` (`ORDER_CREATED` / `WAIT4PICKUP` → `label_created`, `SC_INBOUND_SUCCESS` / `LH_DEPART` / `CC_IM_SUCCESS` → `in_transit`, `DELIVERING` / `WAIT4SIGN` → `out_for_delivery`, `DELIVERED` / `SIGN_SUCCESS` → `delivered`, `RETURNED_SIGN` → `returned`).

## Chaining Last-Mile Handoffs & Consolidated Orders (`message`)

Cainiao's top-level `message` surfaces two critical cross-border links when present:

1. **Last-mile carrier exchange number**: `"Handed to the destination carrier as <realMailNo>"` (e.g. a [USPS](/carriers/usps) `926129…`, [UniUni](/carriers/uniuni) `UUS…`, [GOFO](/carriers/gofo) `GFUS…`, or [OnTrac](/carriers/ontrac) `1LS…` number). Pass that number to `GET /v1/track/{realMailNo}` for detailed doorstep scans and city/state destination data.
2. **Consolidated shipment master number**: `"Shipped together as <mailNo>"` when multiple AliExpress items are combined into a single upgraded parcel at Cainiao's consolidation warehouse.

## Related Resources

- **Live browser lookup tool**: [Track a Cainiao package live on lastscanned.com/lookup/cainiao](https://lastscanned.com/lookup/cainiao)
- **Carrier hub**: [All 31 supported carriers](/carriers)
- **Regex & check digits**: [Tracking number formats & auto-detection](/formats)
- **AI support workflows**: [WISMO AI agents & synchronous tracking](/wismo)