Parcel

Features

• Deliveries sensor: number of active deliveries, with every delivery (status, carrier, events, expected date) as attributes
• Deliveries calendar: one event per active delivery on its expected date
• parcel.add_delivery action to add a delivery from an automation, a script or the card
• parcel.refresh action to force an update
• custom:parcel-card card, shipped with the integration and loaded automatically: list of deliveries, events on click, add form with carrier search
• custom:parcel-mini-card compact card: active deliveries and deliveries arriving today, with a button to open the full card
• parcel_out_for_delivery and parcel_delivered events when a delivery changes status, for automations
• Notifications to the notify actions of your choice when a delivery is out for delivery or delivered, with no automation to write
• Diagnostics download with the API key, tracking numbers, addresses and emails redacted
• API key entered in the UI, never in YAML
• English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek

Prerequisites

• Home Assistant 2024.12 or later
• A Parcel Premium subscription (the API is reserved to it)
• An API key, generated on web.parcelapp.net

Configuration

Integration#

Settings → Devices & services → Add integration → Parcel, then paste your API key.

Options (Configure button):

Card#

Add the Parcel card from the card picker: every option is set in the visual editor. In YAML:

type: custom:parcel-card

Click a delivery to see its events, and the tracking number to copy it.

Mini card#

A compact card for dashboards: the number of active deliveries and of deliveries arriving today (out for delivery, or expected today). The button at the top right opens the full card in place; a click outside the card folds it back.

type: custom:parcel-mini-card

It takes the same options as custom:parcel-card (set in the same visual editor); show_delivered, show_add, show_refresh and max_events apply to the full view.

Adding a delivery from an automation#

action: parcel.add_delivery
data:
  tracking_number: "6A12345678901"
  carrier_code: colissimo
  description: Headphones
  send_push_confirmation: true

Carrier codes are listed in supported_carriers.json. Use pholder for a delivery without tracking.

Parcel limits additions to 20 per day, failures included. A new delivery shows up after Parcel's next update.

parcel.add_delivery is reserved to administrators (the card hides its add button from other users); parcel.refresh is open to every user. Service errors are translated in the Home Assistant language.

Events#

The integration fires an event on the Home Assistant event bus when a delivery changes status between two updates:

Event data: config_entry_id, carrier_code, carrier (carrier name), name (the delivery description) and tracking_id, a stable short hash of the carrier and tracking number (the same for both events of a delivery). The tracking number itself is left out, since events are stored in the recorder and the logbook.

Nothing fires at startup, after a reload or for a delivery seen for the first time. With the Active filter, Parcel drops delivered parcels from the list instead of changing their status: there, parcel_delivered fires when a delivery that was not yet delivered is missing from two successful updates in a row (a delivery deleted in the Parcel app fires it too). An empty list right after a non-empty one is ignored as a likely API glitch, so when every parcel leaves the list at once the event comes one update later.

triggers:
  - trigger: event
    event_type: parcel_delivered
actions:
  - action: notify.mobile_app_phone
    data:
      title: Parcel delivered
      message: "{{ trigger.event.data.name }} ({{ trigger.event.data.carrier }}) has been delivered."

Calendar#

Each account also gets a calendar, calendar.parcel_deliveries, with one event per delivery not yet delivered that has an expected date: an all-day event when Parcel gives only a day (over several days for a delivery window), a timed event otherwise (one hour long when Parcel gives no end). The event title is the delivery description, its description the carrier name; the tracking number is left out. Show it in the calendar dashboard or a calendar card, or trigger automations on it:

triggers:
  - trigger: calendar
    event: start
    entity_id: calendar.parcel_deliveries
actions:
  - action: notify.mobile_app_phone
    data:
      message: "{{ trigger.calendar_event.summary }} is expected today."

Diagnostics#

Settings → Devices & services → Parcel → ⋮ → Download diagnostics gives the entry options and the last deliveries, for bug reports. The API key, tracking numbers, event locations, extra carrier information (often a pickup address), postcodes and emails are redacted.

How it works

The integration polls the Parcel API at the update interval and exposes the deliveries on one sensor and one calendar per account. When an update fails (hourly request limit reached, timeout, Parcel server error), the sensor keeps the last deliveries until the next update and flags them with its stale (true) and last_error attributes; only a refused API key makes it unavailable. The card reads that sensor, sorts active deliveries first by expected date, and colors each status from the Home Assistant theme:

Support

If you find this project useful, you can support its development:

Features

• show_title option (also in the visual editor) hides the header's title, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Maintenance

• No code change: released again to check the installation from the Marketplace.

Features

• Notifications (option Notify actions): the notify actions chosen are told when a delivery is out for delivery or delivered — its name and carrier, in Home Assistant's language, tagged with the delivery so the second replaces the first on a phone. The same transitions as the parcel_out_for_delivery and parcel_delivered events, no automation needed.

Performance

• Translations load on demand: in the release zip, the frontend files keep English only (parcel-card.js 83 KB → 65 KB) and each other language is its own <file>.i18n.<lang>.js file next to them, fetched the first time a card or the panel needs it. Home Assistant loads the card on every dashboard, so each page used to download and parse all 22 languages to use one. The cards and panel are defined once the page's language has arrived (a few milliseconds), so they render translated from the start.

Maintenance

• The Marketplace now installs the release zip (zip_release), like the other ha-* integrations: the split files are only in it.
• The repository keeps every language in the sources: the release runs scripts/split-frontend.mjs before building the zip, and the Validate workflow checks the split on a copy (every table is rebuilt from the split files and compared).

Fixes

• The card's refresh and add buttons now have the same size as the icon actions of the other cards (28 px button, 16 px icon) instead of Home Assistant's larger default.

What's new

• With the Active filter, parcel_delivered now fires when a delivery not yet delivered leaves the list, since Parcel drops delivered parcels there.
• A delivery must be missing from two successful updates in a row, and an empty list right after a non-empty one is ignored, so a partial or empty API reply fires no false parcel_delivered.
• Service errors are translated in the 23 languages, and the card shows them in the Home Assistant language.

Fixes

• A timeout or a Parcel server error now keeps the last deliveries, like the rate limit, instead of making the sensor unavailable; the new stale and last_error sensor attributes flag it.

Security

• parcel.add_delivery is now reserved to administrators, and the card hides its add button from other users.