💬 Questions or feedback? Join the discussion on the Home Assistant community.
A custom Home Assistant integration that tracks your Budbee parcels — home deliveries and Budbee Box lockers, in the Netherlands, Belgium, Sweden, Denmark, Finland and Norway. No account is needed, and no e-mail address either: you enter the tracking or order number and that is it.
Part of the ha-parcel-integrations family: it publishes the same canonical parcel format, statuses and events as the other carrier integrations, so it plugs straight into the Parcel Aggregator and cross-carrier automations.
- Features
- Requirements
- Installation
- Configuration
- Options
- Dynamic polling
- Removal
- Sensors
- Parcel status reference
- Events
- Services
- Examples
- Debugging
- Troubleshooting
- Related integrations
- Disclaimer
- Contributing
- License
- Track any number of Budbee parcels by tracking code — no account needed
- Per-parcel sensor with the canonical status (
registered/in_transit/out_for_delivery/delivered/ …), the carrier's own status text, the expected delivery window and a tracking deep-link - Summary sensors: incoming parcels, next delivery, recently delivered parcels
- Read-only Deliveries calendar with the expected delivery windows
budbee.track_parcel/budbee.untrack_parcelservices, so a dashboard button can add a parcel- Events + device triggers for no-code automations (parcel registered, status changed, delivered, delivery time changed)
- Parcels you send back through Budbee get their own summary sensors and events
- A parcel in a Budbee Box reports
at_pickup_point, and only counts as delivered once you have actually collected it - Manual refresh button and a diagnostic last-update sensor
- A Budbee parcel and its tracking or order number, from the shipping confirmation or the tracking link the shop sent you — no account and no e-mail address needed
- In HACS, choose the three-dot menu → Custom repositories.
- Add
https://github.com/ha-parcel-integrations/ha-budbeeas an Integration. - Install Budbee and restart Home Assistant.
Copy custom_components/budbee into your config/custom_components/ folder and restart Home Assistant.
Add the integration via Settings → Devices & Services → Add Integration → Budbee. There is nothing to fill in: the hub is created immediately (Budbee tracking needs no account).
Then add parcels via the integration's Configure dialog, the budbee.track_parcel service, or a dashboard button. The tracking code is the order number in your shipping confirmation, or the last part of the track.budbee.com/… link the shop sent you.
Budbee's own tracking page also asks for the e-mail address the order was placed with. This integration does not: that second factor only unmasks your own name, address and phone number in the response, which the integration has no use for.
Open Configure on the integration entry:
| Section | Option | Default | Description |
|---|---|---|---|
| Parcels | Add / remove | — | Manage the tracked tracking codes. Changes apply immediately, no restart. |
| Delivered parcels | Filter by / amount | last 7 days | How long delivered parcels stay visible on the delivered sensor. |
There is no parcel history option here, unlike the other integrations in the family: Budbee publishes no event timeline, so every parcel's history attribute is null.
Instead of polling Budbee at the same rate around the clock, the integration adjusts its own cadence to what your tracked parcels — sent and received — are actually doing:
- Quiet hours — no polling between 00:00–06:00 local time, aside from one catch-up check at each end of that window (around midnight and around 6 AM), so an overnight update is never missed.
- Hot (every 15 minutes) — while any tracked parcel is out for delivery today, starting an hour before its delivery window opens (or immediately if no window is known yet).
- Normal (every 45 minutes) — for anything else still on its way.
- Fully paused — once every tracked parcel has been delivered, or nothing is tracked at all, polling stops until you add a parcel back (adding one always triggers an immediate check, regardless of the pause).
- A small, fixed per-hub offset is added on top, so not every Budbee hub out there polls at exactly the same second.
Standard HA removal applies: Settings → Devices & Services → Budbee → ⋮ → Delete. Nothing is stored on Budbee's side.
| Entity | Description |
|---|---|
sensor.budbee_incoming_parcels |
Number of active tracked parcels, full list under the parcels attribute |
sensor.budbee_parcel_<code> |
One per tracked parcel; state is the canonical status, attributes carry the full normalised parcel |
sensor.budbee_next_delivery |
Earliest expected delivery moment across all active parcels |
sensor.budbee_delivered_parcels |
Recently delivered parcels (see the retention option) |
sensor.budbee_outgoing_parcels |
Parcels you are sending back through Budbee |
sensor.budbee_delivered_outgoing_parcels |
Recently completed outgoing parcels |
sensor.budbee_last_successful_update |
Diagnostic: when Budbee was last polled successfully |
A delivered parcel moves from its per-parcel sensor to the delivered sensor automatically.
A calendar.budbee_deliveries entity shows expected delivery dates for
active parcels — read-only, no extra API calls.
A button.budbee_refresh entity forces an immediate poll, without waiting
for the next scheduled interval.
The status field is the carrier-agnostic enum shared by the whole integration family:
| Status | Meaning |
|---|---|
registered |
Booked with Budbee, not collected from the shop yet |
in_transit |
Collected, in the network |
out_for_delivery |
With the courier today (home deliveries only) |
at_pickup_point |
Waiting for you in the Budbee Box |
delivered |
Handed over — for a locker parcel, collected by you |
returning |
On its way back to the shop |
problem |
A delivery attempt failed, or the parcel was not collected in time |
unknown |
Budbee does not know this code yet, or reported a status we have not mapped |
Budbee's own status is always available as raw_status.
Budbee Box parcels are the reason this matters. Budbee reports Delivered
the moment a parcel goes into the locker, which is not the same as you having
it. This integration maps that to at_pickup_point; delivered only fires once
Budbee reports PickedUp.
The integration fires these on the event bus (also available as device triggers on the Budbee device):
| Event | When |
|---|---|
budbee_parcel_registered |
A new parcel appears in the active list |
budbee_parcel_status_changed |
A parcel's canonical status changes (old_status / new_status in the payload), except the final hop to delivered |
budbee_parcel_delivered |
A parcel is delivered |
budbee_parcel_delivery_time_changed |
The expected delivery window changes |
budbee_outgoing_parcel_status_changed |
A parcel you are sending changes status |
budbee_outgoing_parcel_delivered |
A parcel you sent reached its destination |
Every payload is the full normalised parcel plus the hub's device_id. Events are suppressed on the first refresh after start-up.
| Service | Fields | Description |
|---|---|---|
budbee.track_parcel |
tracking_code |
Start tracking a parcel |
budbee.untrack_parcel |
tracking_code |
Stop tracking a parcel |
Ready-to-paste automations and dashboard snippets live in examples/, including tracking a new parcel straight from a dashboard.
Third-party cards that work with this integration's sensors:
logger:
logs:
custom_components.budbee: debug- A parcel shows
unknown— Budbee does not know the number yet (their API answersORDER_NOT_FOUNDuntil the shop hands the parcel over), or the number is wrong. It picks up automatically once Budbee registers it. - No expected delivery time on a locker parcel until it reaches a terminal — a Budbee Box order only gets an ETA once it's on its final leg to the locker; before that,
planned_tois empty. It never gets a collection deadline either — that's a different date (when you must pick it up) and stays under the raw attribute, not the delivery window. - No status history — Budbee's tracking API returns no event list at all, so the
historyattribute is always empty. - A status logs "Unrecognised Budbee status" — please open an issue with the logged line so the mapping can be extended.
This integration is part of ha-parcel-integrations — a family of parcel-carrier integrations that all publish the same canonical parcel format, statuses and events.
- Parcel Aggregator rolls every installed carrier up into one set of sensors.
- Browse the organisation for the current list of supported carriers.
This is an independent, community-built project. It is not affiliated with, endorsed by, sponsored by, or supported by Budbee, Home Assistant, or any other third party referenced in this project. Please don't contact Budbee for support with this integration.
All third-party trademarks, trade names, product names, logos, and other brand assets are the property of their respective owners. References to them are solely to identify the relevant carrier or service and do not imply affiliation, sponsorship, or endorsement. Nothing in this project grants or implies any licence or right to use third-party brand assets.
This integration may rely on public, unofficial, or undocumented carrier interfaces, accessed with your own account or API key where required. These may change or be withdrawn without notice and may be subject to Budbee's terms. Data is sent only to Budbee's own services or those of its group; this project operates no servers of its own. You are responsible for ensuring that your use complies with applicable law and those terms. Use is at your own risk; see the licence for warranty limitations.
This integration uses the same public tracking endpoint as Budbee's own consumer tracking page, and reads only. Be gentle with the polling interval.
Pull requests and issues are welcome. Please open an issue before submitting a large change.