Integration contract¶
HA Parcel Card doesn't have per-carrier logic for parsing tracking data — every carrier is read
through the same canonical parcel format. Any Home Assistant integration that exposes its
data this way works with the card today, with type: custom and zero changes to the card
itself. This page documents that format for integration authors.
If you maintain (or are writing) a parcel-tracking integration and want your users to be able to use this card, this is the contract to match.
Two levels of support¶
- Works via
type: custom— the only requirement is the sensor attribute shape below. No auto-detection, no branded logo/van/banner (a generic icon is used unless the user supplieslogo_path/van_path/banner_paththemselves), no automatic sensor discovery — the user configuresentity_incoming/entity_delivered/etc by hand. This is the whole contract; you don't need anyone's permission or involvement to support it. - First-class support (a dedicated carrier preset — proper name, branding, colour, an entry in the carrier-type dropdown, and automatic account detection when the card is added to a dashboard) — open an issue or PR on this repo once your integration exposes the canonical format. Most first-class carriers today are part of ha-parcel-integrations, but that's not a requirement — it's just where most of them happened to end up.
Sensor shape¶
Each carrier is read from up to five sensors (letters only apply to PostNL-style mailbox integrations, and outgoing/outgoing-delivered only apply if you track sent parcels too):
| Card config field | Purpose |
|---|---|
entity_incoming |
Parcels on their way to the user |
entity_delivered |
Parcels already delivered to the user |
entity_outgoing |
Parcels the user has sent, in transit (optional) |
entity_outgoing_delivered |
Parcels the user has sent, delivered (optional) |
entity_letters |
Mailbox/letter items (optional, PostNL-style only) |
Each sensor's state is not read at all by the card — only its attributes matter. The
attributes must resolve (via _extractRawList) to a plain array of parcel
objects, found via the first of these that matches:
- The attributes themselves are an array (rare — most integrations expose an object of attributes, not a bare array state attribute, but it's supported).
- An
enroute/en_routearray attribute plus adeliveredarray attribute — both are read and concatenated (a legacy shape some integrations use to split active/delivered within one sensor's attributes; if you're starting fresh, prefer separateentity_incoming/entity_deliveredsensors instead and skip this entirely). - A
shipmentsarray attribute. - A
parcelsarray attribute. - A
lettersarray attribute (letters sensor only). - Falls back to every attribute value that is itself an object (i.e. attributes keyed by tracking number rather than a single array).
Attribute-key matching is case-insensitive.
Parcel object shape¶
Every item in that array should look like this. Only status is truly required — everything
else has a sane fallback, but the more you provide, the more the card can show.
{
// One of: registered, in_transit, out_for_delivery, at_pickup_point, delivered,
// returning, problem, unknown. Case-insensitive (ha-postnl v4.x sends UPPERCASE,
// most others lowercase — the card normalizes this itself, don't worry about casing).
"status": "in_transit",
// Optional. If omitted, derived from status (true only for "delivered").
// Provide it explicitly if your integration has a more precise signal.
"delivered": false,
// A stable unique identifier for this parcel - tracking number, barcode, whatever
// is unique per shipment. Falls back to `barcode` or `id` if `key` isn't present.
"key": "3SABCD1234567",
// Optional. Either works - `name` wins if both are present. If neither is set,
// the card shows a generic "Unknown parcel" label.
"name": "Order #4471",
"sender": "Some Webshop",
// Optional dates (ISO 8601 strings, or anything `new Date()` accepts). Used for
// sorting and the days_back cutoff filter. delivered_at wins over planned_from
// wins over delivery_date, when more than one is present.
"delivered_at": "2026-08-14T14:32:00+02:00",
"planned_from": "2026-08-15T00:00:00+02:00",
// Optional. true only for a genuine pickup-point/locker delivery (never a plain
// "left with a neighbour" home delivery) - adds a 5th step to the tracker between
// "out for delivery" and "delivered".
"pickup": false,
// Optional, only meaningful with status at_pickup_point: the last moment the parcel can
// be collected before it goes back to the sender. The card then shows "2 days left to
// collect" instead of how long it has been waiting (taken from `history`). Without it, the
// card reads the deadline some carriers keep in `raw` (Česká pošta, Matkahuolto, Budbee,
// Mondial Relay accounts) — sending it here is the portable way.
"pickup_deadline": "2026-10-30T23:59:00+01:00",
// Optional. Shown in the detail panel when the user enables show_raw_status,
// instead of the card's own generic translated label for this status.
"raw_status": "Onderweg - geladen voor aflevering",
// Optional. Carrier-specific extra fields. Never blindly dumped - only shown if
// this repo's CARRIER_EXTRA_DETAILS has a mapping function for your carrier type.
// Open a PR to add one once you have a real field worth surfacing (weight,
// dimensions, a delivery code, etc).
"raw": { }
}
Letters (mailbox items)¶
entity_letters items use a different, smaller shape - date/delivery_date, title,
unread (boolean), id/key, and image_url for a scan image (a URL ending in something
matched against /letter_placeholder/i is treated as "not ready yet" and skipped). Letters are
currently a PostNL-specific concept (ha-postnl's own mailbox-scan feature) - if your
integration has something equivalent, open an issue to discuss the shape before building against
it, since this side of the contract is far less generalized than the parcel shape above.
Auto-detection (optional, needed only for first-class support)¶
The card can auto-populate a carrier entry when first added to a dashboard, by finding your
integration's sensors and guessing entity_incoming/entity_delivered/etc. Two mechanisms,
tried in order:
translation_keymatching (preferred) — if your entities usehas_entity_name(the modern HA entity-naming convention) with stable, English, unlocalizedtranslation_keyvalues (incoming_parcels,delivered_parcels,outgoing_parcels,outgoing_delivered_parcels,letters), detection works correctly regardless of what language the user's Home Assistant frontend is set to. This is the only approach that's actually language-proof — see theregistryEntitiesByDevice/repairStaleEntityIdcomments inha-parcel-card.jsfor the history of why (an integration's entity_id suffix is derived from whatever language was active when the entity was first created, not fromtranslation_key, so text-guessing alone breaks the moment a user's language differs from what the card expects).- Entity ID text-guessing (fallback) —
sensor.<user>_incoming_parcels,sensor.<user>_delivered_parcels, etc. (English suffixes), tried in both<user>_<suffix>and<suffix>_<user>order. Works withouttranslation_key, but only for the specific suffix words the card already knows about.
If you want first-class support, using has_entity_name + the translation_key values above is
the most robust option — reach out (open an issue) if you'd like help wiring this up.
Not part of the contract¶
- The sensor's own state value — the card never reads it, only attributes.
- Any specific HA domain name for your integration —
type: customdoesn't care what your integration is called. - Icons/branding — bring your own via
logo_path/van_path/banner_path, or ask for a preset (see above).