Cainiao Tracking API & MCP

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 FactsCopy Anchor Link

Why developers use lastscanned for CainiaoCopy Anchor Link

• 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)Copy Anchor Link

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

When is ?carrier=cainiao optional vs required?Copy Anchor Link

• 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 ResponseCopy Anchor Link

curlCopy Anchor Link

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

JavaScript / TypeScript (fetch)Copy Anchor Link

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 callCopy Anchor Link

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

Normalized TrackingResult JSON responseCopy Anchor Link

{
  "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)Copy Anchor Link

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 926129…, UniUni UUS…, GOFO GFUS…, or 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 ResourcesCopy Anchor Link

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