IsItPayday is a custom integration for Home Assistant that calculates and displays your next payday based on your country's public and bank holidays and your chosen pay frequency.
All calculations are performed locally using the holidays Python package - no cloud services, external API, or internet connection required.
-
Device-based integration: All entities are grouped under a single device for each configured instance.
-
Binary Sensor:
binary_sensor.<instance_name>_is_it_payday -
Sensor:
sensor.<instance_name>_next_payday- Displays the date of the next payday.
- Exposes extra attributes:
upcoming_paydays(the next several paydays),paydays_this_month(remaining paydays in the current month) andpaydays_this_month_count. - Icon:
mdi:calendar-clock. (See icon)
-
Sensor:
sensor.<instance_name>_days_to- Displays how many days until next payday.
- Icon:
mdi:calendar-end. (See icon)
-
Sensor:
sensor.<instance_name>_last_payday- Displays the most recent payday on or before today.
- Icon:
mdi:calendar-check. (See icon)
-
Calendar:
calendar.<instance_name>_payday- Shows your upcoming paydays as all-day calendar events.
- Multiple future paydays are displayed, not just the next one.
- Automatically updates when paydays change.
-
Custom Payday Calculation:
- Supports various pay frequencies:
- Weekly
- Every 14 days
- Every 28 days
- Monthly
- Every 2 months
- Quarterly (every 3 months)
- Semi-annually (every 6 months)
- Annually
- Supports various pay frequencies:
-
Automatic Adjustment for Holidays and Weekends:
- Public holidays and bank holidays (where available) are calculated locally using the holidays Python package.
- Adjusts payday if it falls on a weekend or holiday.
- Works fully offline - no internet connection or external API required.
-
Regional Holiday Support:
- For countries with regional holidays (e.g. German Bundesländer or US states), you can select your state/region during setup for the most accurate holiday calendar.
-
Payday Event:
- Fires an
isitpayday_paydayevent on each payday, at a time of day you choose (default 06:00). Automations can trigger directly on this event.
- Fires an
-
Options Flow:
- After initial setup, you can adjust all settings via the Configure button in the Devices & Services section. The integration reloads automatically when settings are saved - no restart required.
-
Diagnostics:
- Downloadable diagnostics (configuration and latest calculation) are available from the device page to make troubleshooting and bug reports easier.
- Add this repository as a custom repository in HACS.
- Search for Is It Payday? in HACS and install the integration.
- Restart Home Assistant.
- Download the latest release.
- Copy the
custom_components/isitpaydayfolder into your Home Assistantcustom_componentsdirectory. - Restart Home Assistant.
- Go to Settings > Devices & Services > Add Integration and search for Is It Payday.
- Enter a name for this instance (e.g.
My Payday). - Choose your country from the dropdown list. The list contains all countries supported by the holidays package. The integration automatically pre-selects your Home Assistant configured country, but you can change it if needed.
- If the selected country has regional holidays, you are asked to select your state/region. Choose Entire country to use only national holidays, or pick a region to include its regional holidays in the calculation.
- Countries without regional holidays skip this step automatically.
- Options:
weekly: Weekly14_days: Every 14th day28_days: Every 28th daymonthly: Monthlybimonthly: Every 2 monthsquarterly: Every 3 monthssemiannual: Every 6 monthsannual: Every year
-
Monthly:
- Options:
last_bank_day: Last bank dayfirst_bank_day: First bank dayspecific_day: Specific day
- Options:
-
Every 14th or 28th day / Every 2 months / Quarterly / Semi-annually / Annually:
- Select last payday: Choose the date of your most recent payday. The integration uses this to calculate all future paydays.
-
Weekly:
- Select weekday: Choose the weekday you receive your payment.
-
If "Last bank day" is selected:
- Days before last bank day (0–10, default 0): Specify how many days before the last bank day you are paid. The resulting date is also validated to be a bank day.
-
If "Specific day" is selected:
- Specific day (1–31, default 31): Choose the exact day of the month. If that day falls on a weekend or holiday, the integration adjusts to the previous working day.
- Choose the time of day the
isitpayday_paydayevent is fired on each payday. The default is 06:00.
| Entity ID | Name | Description |
|---|---|---|
binary_sensor.<instance_name>_is_it_payday |
Is It Payday? | on if today is payday, otherwise off. |
sensor.<instance_name>_next_payday |
Next Payday | Date of the next payday (YYYY-MM-DD). |
sensor.<instance_name>_days_to |
Days until | Number of days until the next payday. |
sensor.<instance_name>_last_payday |
Last Payday | Most recent payday on or before today. |
calendar.<instance_name>_payday |
Payday | All-day calendar events for upcoming paydays. |
All entities are grouped under a single device, named after your chosen Instance Name during setup.
The Next Payday sensor exposes additional attributes useful for automations:
| Attribute | Description |
|---|---|
upcoming_paydays |
List of the upcoming paydays (YYYY-MM-DD). |
paydays_this_month |
Remaining paydays in the current calendar month. |
paydays_this_month_count |
Number of remaining paydays this month (handy for biweekly pay). |
On each payday, at the configured time of day (default 06:00), the integration fires an event on the Home Assistant event bus:
- Event type:
isitpayday_payday - Event data:
entry_id– the config entry idname– the instance namedate– the payday date (YYYY-MM-DD)
You can change the event time at any time via Configure.
automation:
- alias: "Notify on payday"
trigger:
- platform: event
event_type: isitpayday_payday
action:
- service: notify.notify
data:
message: "It's payday! 🎉"After the integration is set up, you can change any setting (country, region, pay frequency, day, event time, etc.) directly from:
Settings > Devices & Services > Is It Payday > Configure
The integration reloads automatically when you save - no restart required. To rename an instance, use the rename (pencil) option on the integration entry.
You can add a Payday Info Card to your Home Assistant dashboard using the following Lovelace YAML configuration:
type: entities
title: Payday Information
entities:
- entity: binary_sensor.my_payday_instance_is_it_payday
name: Is It Payday Today?
- entity: sensor.my_payday_instance_next_payday
name: Next Payday Date
- entity: sensor.my_payday_instance_days_to
name: Days Until Payday
- entity: sensor.my_payday_instance_last_payday
name: Last Payday
- entity: calendar.my_payday_instance_payday
name: Payday CalendarSensors show "Unknown"
- Check the Home Assistant logs for messages from
custom_components.isitpayday- they will indicate if the configured country or pay settings are invalid. - Verify that the selected country is supported by the holidays package.
Payday date seems wrong
- Make sure the correct pay frequency and reference date (last payday) are configured.
- If you use "Last bank day with offset", verify that the offset does not push the date into a weekend or holiday — the integration adjusts automatically, but double-check in the logs.
- For regional holidays, make sure the correct state/region is selected via Configure.
Payday event does not fire
- The event fires once per payday at the configured time. If Home Assistant is not running at that time, the event fires once when it next starts up that day.
- Check Developer Tools > Events and listen for
isitpayday_paydayto verify.
Integration fails to load
- Check the Home Assistant logs under Settings > System > Logs and look for entries from
custom_components.isitpayday. - Download diagnostics from the device page and attach them to a bug report.
- Try removing and re-adding the integration.
If you encounter any issues or have feature requests, please open an issue on GitHub:
This integration is licensed under the MIT License.