Ali Express Tracking

AliExpress Tracking Checker – Multi-Source Shipment Tracking & Cainiao Scraper

Track AliExpress shipments using a multi-source engine: Cainiao Global, AliExpress logistics, and 17TRACK public tracking pages. This actor walks a configurable priority list of providers and returns normalized, structured tracking data from the first source that succeeds.

Overview

AliExpress Tracking Checker uses Playwright (Chromium) to open public tracking pages, intercept JSON responses, and parse DOM content when needed. It normalizes carrier, status, locations, and event history into one consistent schema.

Output is compact: empty or missing fields are omitted so each row contains only what the tracking sources exposed for that shipment.

Key benefits

• Check multiple tracking numbers in one run via trackingInputs
• Multi-source fallback with configurable sourcePriority
• Normalized status (in_transit, delivered, exception, etc.)
• Optional full event timeline per shipment
• Export clean datasets in JSON, CSV, or Excel via Apify
• Proxy and cookie support for anti-bot tracking sites

Core features

• Cainiao, AliExpress, and 17TRACK web adapters (priority-based)
• Bulk tracking input with optional orderId, carrierHint, sourceHint, countryHint
• Derived status flags: delivered, inTransit, exception
• Event history with maxEventsPerTracking cap
• Optional raw source payload for debugging
• Parallel lookups via maxConcurrency
• Output to dataset, key-value store, or both (outputMode)

How to Use AliExpress Tracking Checker on Apify

Using the Actor

1. Open the Actor on the Apify platform and go to the Input tab.
2. Add tracking numbers in trackingInputs (with optional order IDs and hints).
3. Enable residential proxy via proxyConfiguration for best reliability.
4. Start the run. The actor tries each source in order and pushes compact items to the default dataset.
5. Open the Dataset tab to browse, download JSON/CSV/Excel, or pull data via the Apify API.
6. Schedule or integrate (optional): use schedules, webhooks, Zapier/Make, or your own code against the Apify API.

Input Configuration

Full schema: INPUT_SCHEMA.json. Example:

{
  "trackingInputs": [
    { "trackingNumber": "LP00123456789012", "orderId": "8182736455463721" },
    { "trackingNumber": "CNABC0012345678", "carrierHint": "Cainiao", "countryHint": "PK" }
  ],
  "sourcePriority": ["cainiao_web", "aliexpress_web", "seventeen_track_web"],
  "includeEventHistory": true,
  "includeDerivedStatus": true,
  "maxConcurrency": 3,
  "outputMode": "dataset",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}

• trackingInputs (required): Array of tracking request objects. Each may include trackingNumber, orderId, carrierHint, sourceHint, and countryHint. Plain strings are accepted as tracking numbers.
• sourcePriority (optional): Ordered list of source adapters. Default: ["cainiao_web", "aliexpress_web", "seventeen_track_web"].
• includeEventHistory (optional): Include the full tracking event timeline (default true).
• includeRawSourcePayload (optional): Include sanitized raw source HTML for debugging (default false).
• includeDerivedStatus (optional): Compute normalized status and delivery flags (default true).
• maxEventsPerTracking (optional): Max events per shipment (default 50, max 500).
• outputMode (optional): dataset, kv_store, or both (default dataset).
• outputKvStoreKey (optional): KV store key when using kv_store or both (default TRACKING_OUTPUT).
• requestTimeoutSecs (optional): Page navigation timeout (default 45).
• maxConcurrency (optional): Parallel tracking lookups (default 5, max 20).
• retriesPerSource (optional): Retries per source before moving on (default 2).
• challengeWaitSecs (optional): Max wait for Cloudflare/CAPTCHA resolution (default 12).
• blockAssets (optional): Block non-essential assets for speed (default true).
• debugMode / saveHtmlSnapshot / saveScreenshot (optional): Debug artifacts for failed pages.
• proxyConfiguration (optional): Apify proxy; residential is recommended.
• cookiesText / cookiesJson (optional): Session cookies. Secret inputs — encrypted at rest, not copied to dataset rows.
• seventeenTrackApiKey (optional): Reserved for future 17TRACK API adapter. Secret input.

Authentication & sensitive input

Fields that can hold session credentials use Apify secret input (isSecret: true):

• cookiesText — Netscape/tab-separated cookie format
• cookiesJson — Playwright cookie array JSON
• seventeenTrackApiKey — future API key storage

Secret values are encrypted in storage and are not written into dataset rows or logs.

Run locally

INPUT.json is gitignored. Copy INPUT.example.json to INPUT.json, then:

cd aliexpress-tracking-checker
pip install -r requirements.txt
playwright install chromium
cp INPUT.example.json INPUT.json
python main.py

Output

Results are stored in the Actor’s default dataset when outputMode is dataset or both. Each item is a compact JSON object: fields that are empty or unknown are not included.

Typical fields (when data is available):

• Identity: trackingNumber, orderId
• Carrier & source: carrier, sourceUsed, sourceUrl, sourceStatusText
• Status: normalizedStatus, delivered, exception, inTransit
• Timing: lastUpdate, estimatedDelivery, firstSeenEvent, latestEvent
• Location: lastUpdateLocation, latestLocation, originCountry, destinationCountry
• Events: trackingEvents, eventCount
• Quality: statusConfidence, sourceAttempts, warnings
• Debug: rawSourcePayload (when enabled)
• Errors: error on failure rows
• Meta: timestamp

Example item (illustrative — real items only include keys that have values):

{
  "trackingNumber": "LB123456789SG",
  "orderId": "8182736455463721",
  "carrier": "Cainiao",
  "sourceUsed": "cainiao_web",
  "sourceUrl": "https://global.cainiao.com/detail.htm?mailNoList=LB123456789SG",
  "sourceStatusText": "Parcel is in transit",
  "normalizedStatus": "in_transit",
  "delivered": false,
  "inTransit": true,
  "lastUpdate": "2026-03-31T10:22:00Z",
  "lastUpdateLocation": "Lahore, Pakistan",
  "estimatedDelivery": "2026-04-07",
  "eventCount": 6,
  "statusConfidence": "high",
  "sourceAttempts": [
    { "source": "cainiao_web", "success": true, "reason": "tracking data found" }
  ],
  "trackingEvents": [
    {
      "timestamp": "2026-03-21T03:10:00Z",
      "status": "Shipment accepted by carrier",
      "location": "Shenzhen, China",
      "details": "Accepted at sorting center",
      "sourceEventIndex": 0
    }
  ],
  "timestamp": "2026-03-31T12:00:00Z"
}

When outputMode is kv_store or both, a JSON bundle with records and summary is also written to the key-value store under outputKvStoreKey (default TRACKING_OUTPUT).

Normalized statuses

Status	Meaning
pending	Label created / information received
accepted	Shipment accepted by carrier
in_transit	Package is moving between facilities
arrived_at_destination_country	Customs clearance or arrival at destination
out_for_delivery	Out for final delivery
delivered	Successfully delivered
failed_attempt	Delivery attempt failed
exception	Held, lost, or other exception
returned	Returned to sender
expired	Tracking expired
unknown	Could not determine status

Failure output

When no source returns valid data (compact — omitted null keys):

{
  "trackingNumber": "LP00123456789012",
  "normalizedStatus": "unknown",
  "error": "No source returned valid tracking data",
  "sourceAttempts": [
    { "source": "cainiao_web", "success": false, "reason": "challenge page persisted" },
    { "source": "aliexpress_web", "success": false, "reason": "no tracking result" }
  ],
  "timestamp": "2026-03-31T12:00:00Z"
}

Use Cases

• Dropshipping order tracking — monitor AliExpress orders and keep customers updated
• Tracking dashboards — feed normalized status into internal monitoring tools
• E-commerce automation — connect tracking data to CRMs and support systems
• Delivery alerts — detect status changes by diffing scheduled runs
• Logistics analytics — analyze shipping times, delays, and carrier performance

Integrations & API

• Run and fetch results through the Apify API
• Use Python, Node.js, or HTTP clients against run and dataset endpoints
• Connect Zapier, Make, Google Sheets, and other Apify integrations
• Webhooks and schedules for recurring tracking checks

FAQ

How does AliExpress Tracking Checker work?

It tries each source in sourcePriority using Playwright, extracts tracking events and status from the first successful source, normalizes the data, and pushes compact rows to the dataset.

Why use multiple tracking sources?

AliExpress shipments often surface updates on Cainiao or 17TRACK before or more completely than on AliExpress pages alone.

Can I track multiple orders in one run?

Yes. Add multiple entries to trackingInputs.

Why am I getting no tracking results?

Invalid numbers, shipments not yet registered, or blocked access are common causes. Use residential proxy and cookies when sources challenge automated traffic.

What formats can I export?

JSON, CSV, and Excel from the Apify dataset UI, plus full access via the Apify API.

SEO Keywords

aliexpress tracking checker
cainiao tracking scraper
aliexpress shipment tracker
17track scraper
shipment tracking api
package tracking automation
apify tracking actor

Actor permissions

This Actor is intended to work with limited permissions: it reads your input and writes to its default dataset (and uses Apify proxy/KV as configured). It does not require broad access to unrelated account data.

To set limited permissions in Apify Console:

1. Open your Actor on the Apify platform.
2. Go to Source or Settings.
3. Open Review permissions / Permissions.
4. Choose Limited permissions and save.

Limitations

• Not all shipments expose the same fields across tracking sources.
• Tracking sites may block automated access or require CAPTCHA solving.
• Session cookies may be needed for some source flows.
• 17TRACK may show limited data for unregistered tracking numbers.
• The actor does not invent tracking data — it only returns what sources expose.
• Heavy use may require higher Apify memory, concurrency, and proxy budgets.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Get Started

Add your tracking numbers, turn on a residential proxy, and start your first run on Apify.