0.9.1

Other improvements

• If a real Cainiao parcel turns out to expose a delivery estimate (we've never seen one, so the next-delivery sensor and calendar stay empty), the integration now flags it so you can help us wire it up.
• Reporting an unrecognised status now shows you how to attach a diagnostics file — which usually contains everything we need to fix it.

0.9.0

The first release of the Cainiao integration — tracking for the cross-border parcels that arrive from AliExpress, Temu, Shein and similar shops.

Why a separate integration? A parcel from China is invisible to PostNL, DHL or DPD until it reaches their network, often two weeks after you ordered. Cainiao sees it from the day it ships, which is exactly the stretch you most want to follow. Once a local carrier takes over the last leg, that carrier's integration picks it up — the two complement each other rather than compete.

No account is needed: you enter the tracking number, usually starting with LP.

New features

• Per-parcel sensors with the canonical status, Cainiao's own status text, the country the parcel left and the one it is heading to, and a link to the tracking page.
• Summary sensors — incoming parcels and recently delivered parcels, each carrying the full parcel list as an attribute so one dashboard card can render everything.
• Events and device triggers for parcel registered, status changed and delivered, so "it finally left China" automations need no polling of your own.
• cainiao.track_parcel / cainiao.untrack_parcel services, so a dashboard button can add a parcel without opening the integration options.
• Opt-in status history — the full customs-and-flights timeline per parcel, at no extra request since Cainiao ships it in the same response.
• Track parcels straight from your e-mail — an example automation reads shipping mails via the core IMAP integration and registers LP… numbers automatically.
• A manual refresh button and a diagnostic sensor showing when Cainiao was last polled successfully.

A deliberately slow poll

The refresh interval is fixed at six hours and cannot be changed. Alibaba throttles traffic it considers unusual, and a block would cost you every AliExpress service, not just this integration. All your parcels are fetched in a single request per poll for the same reason.

A parcel that spends three weeks crossing a continent loses nothing by being checked four times a day — and the refresh button is there when you cannot wait.

Known limitation — and how you can help

Cainiao describes each scan with an action code. This release maps 31 of them, cross-checked between two independently maintained trackers, but the list is certainly not complete. An unrecognised code makes the parcel report unknown rather than guessing, and writes one line to your log with a ready-made issue link.

Opening that issue with the logged line is all it takes. The code alone is enough — it says nothing about you or your parcel.

Worth reporting too: a status that feels wrong rather than unknown, such as a parcel claiming to be delivered while it is still at a pickup point. Those mappings are the ones with the least evidence behind them, and that is why this is 0.9.0 rather than 1.0.0.

Installation

Add https://github.com/ha-parcel-integrations/ha-cainiao to HACS as a custom repository, install Cainiao, and restart Home Assistant.