This update adds four powerful new attributes (found in the Monthly Summary sensor under the Extras device) to help you catch issues early and keep your budget clean:
unapproved_transactions- Number of transactions that haven’t been approved this monthuncleared_transactions- Count of “uncleared” transactions from selected active accountsoverspent_categories- Number of categories currently in the red (negative balance)needs_attention_count- Combined count of the above three flags (range: 0–3)
Use these attributes to build “attention-needed” cards or alerts in your dashboard — no extra templates or helpers needed.
- Multiple Budgets: Configure multiple YNAB budgets.
- Configurable Update Intervals: Choose how frequently each budget’s data is refreshed.
- Account Balances: Pull real-time balances for any on-budget account and associated attributes.
- Category Sensors: Track each category’s balances and associated attributes.
- Custom Budget “Instance Name”: Each budget can have a unique prefix (e.g., “Mel,” “Jamie”) to avoid entity ID collisions. (Defaults to the YNAB budget name)
- Currency Selection: Choose your preferred currency (USD, EUR, etc.).
- Monthly Summary Sensors: Retrieve current month's summary data with associated attributes (e.g.,
Budgeted,Activity,To Be Budgeted,Age of Money).
Below are screenshots showcasing an example card on a dashboard, the integration setup and how YNAB data appears in Home Assistant.
You can see the dashboard card example, setup flow, account details, category insights, and the new monthly summary sensor in action.
 |
 |
 |
 |
 |
- Ensure HACS is installed. If you haven’t yet installed HACS, follow the HACS installation guide.
- In Home Assistant, open HACS from the sidebar.
- Click on the search bar at the top.
- Type “YNAB Integration for Home Assistant” and select it.
- Click Install.
- Restart Home Assistant to finalize the installation.
- Download the latest release from the GitHub repository.
- Unzip the downloaded file and place the
ynab_customfolder inside yourcustom_componentsdirectory (e.g.,/config/custom_components/ynab_custom). - Restart Home Assistant.
- Go to Settings → Devices & Services → Integrations in Home Assistant.
- Click "+ Add Integration" and search for "YNAB Integration for Home Assistant".
- Enter your YNAB API Key (see below for instructions).
- Accept terms and conditions
- Select your budget from the dropdown/list.
- Choose an instance_name or leave default.
- Pick your preferred currency (USD, EUR, etc.).
- Choose your desired update_interval or leave default (Longer intervals are better to not make too many API calls and not be rate limited).
- Select Accounts & Categories to include or leave as Select All.
- Go to YNAB Developer Settings.
- Click "New Token" to generate a personal access token.
- Copy the API Key and use it during integration setup.
YNAB data is represented using compact, attribute-rich sensors — each account, category, and summary uses a single sensor packed with all relevant details.
Each YNAB account is represented by a single sensor containing key financial attributes like balance, cleared total, and account type.
- Balance – The total balance of the account, including both cleared and uncleared transactions.
- Cleared Balance (Default state value) – The balance of transactions that have been processed and cleared.
- Uncleared Balance – The balance of pending transactions that have not yet cleared.
- On Budget – Indicates whether the account is included in the budget (
truefor budgeted accounts,falsefor tracking accounts). - Type – The type of account (e.g.,
Checking,Credit Card,Savings).
Each category in your YNAB budget is exposed as a single, attribute-rich sensor that includes budgeted amount, spending, remaining balance, and goal tracking.
- Budgeted – The amount of money assigned to this category for the current month.
- Activity – The total amount spent in this category during the current month (negative means an expense).
- Balance (Default state value) – The remaining funds available in this category after subtracting activity from budgeted.
- Category Group – The parent group this category belongs to (e.g., "Bills," "Groceries").
- Goal Type – The type of goal set for this category (e.g.,
Target Balance,Monthly Funding). - Goal Target – The total amount you aim to allocate or save for this category.
- Goal Percentage Complete – The percentage of progress toward the goal, based on the balance and target.
- Goal Overall Left – Remaining amount needed to meet the goal target.
- Percentage Spent – How much of the current month’s budget has been spent (0 – 100 %+).
- Needs Attention –
trueif the category is overspent or under‑funded. - Attention Reason –
"Overspent","Underfunded", or"Ok".
The Monthly Summary sensor, located under the Extras device, provides an overview of your current budget’s performance — including total activity, money to be budgeted, and average age of money.
- Budgeted – The total amount of money assigned for the current month.
- Activity – (Default state value) The total amount spent for the current month.
- To Be Budgeted – The remaining funds available to be assigned for the current month.
- Age Of Money – The average age of your money, indicating financial stability.
- Unapproved Transactions – Transactions that haven’t been manually approved
- Uncleared Transactions – Still-pending transactions from active accounts
- Overspent Categories – Categories that went negative this month
- Needs Attention Count – A quick 0–3 score based on how many of the above are true
- Found a bug? Report it via GitHub Issues.
- Have a feature request? Feel free to suggest improvements.
- Pull requests are welcome!
This version introduces smarter handling of hidden categories, improving dashboard clarity:
- Hidden YNAB categories now include a
hidden: trueattribute. - Sensor names auto-append
(Hidden)if the category is hidden in YNAB. - This makes it easy to exclude legacy or unused categories using templates.
Four new Category‑sensor attributes for cleaner dashboards—no extra templates needed!
| Attribute | What it does |
|---|---|
percentage_spent |
% of this month’s budget already spent (0 % when nothing budgeted). |
needs_attention |
true / false flag if the category is Overspent or Under‑funded. |
attention_reason |
"Overspent", "Underfunded", or "Ok" so you know why. |
goal_overall_left |
Money still required to hit the goal target, converted to your currency. |
These are calculated inside the integration—no extra API calls, no new entities.
I'm actively improving the YNAB integration and plan to introduce the following features in future updates:
-
Scheduled Transactions: Support for upcoming transactions that haven't been processed yet.
-
Category Group Summaries & Budget-Wide Summaries: Previously available but currently not included; I plan to explore reintroducing them in a similar method to the Accounts, Categories & Monthly Summary
-
Manual Refresh Service (
ynab_custom.refresh): Not present in this release but may return in a future update. -
Integration "Configure" option - This may be reintroduced in a future update.
-
Optional Exclusion of Hidden Categories – Considering a toggle in the config flow to exclude hidden categories from being created as sensors, for cleaner dashboards.
If you enjoy this integration, consider supporting development:
🚀 Happy budgeting with Home Assistant! 🎯
This YNAB for Home Assistant integration is not officially supported by You Need A Budget (YNAB) in any way. Use of this integration is at your own risk. Any issues or errors caused by this integration are not supported through YNAB's official support channels, and YNAB will not be able to troubleshoot or fix any problems related to it. Please use at your own risk!
