• Home Assistant Statistics API now fully supported for all YNAB sensors
• Programmatic data access - use YNAB data in automations, scripts, and custom dashboards
• Rich statistical data - access state, change, and sum values for account and category balances

• "Configure" button now available in integration settings - no more re-installing to change settings!
• Instance name changes - update your budget's display name anytime
• Currency format updates - change currency display without reinstalling
• Update interval changes - adjust refresh frequency without reinstalling
• Dynamic account/category selection - add/remove accounts and categories after setup
• Filter toggles - include/exclude closed accounts and hidden categories anytime

• Comprehensive API status sensor with detailed rate limit tracking
• Persistent data storage - sensors retain data during rate limits and HA restarts
• Intelligent status detection - accurately shows "Rate Limited" vs "Connected" status
• Request tracking - monitor API usage across all YNAB integrations
• Rolling window rate limit - proper calculation of when rate limits reset

• 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.

1. Ensure HACS is installed. If you haven’t yet installed HACS, follow the HACS installation guide.
2. In Home Assistant, open HACS from the sidebar.
3. Click on the search bar at the top.
4. Type “YNAB Integration for Home Assistant” and select it.
5. Click Install.
6. Restart Home Assistant to finalize the installation.

1. Download the latest release from the GitHub repository.
2. Unzip the downloaded file and place the ynab_custom folder inside your custom_components directory (e.g., /config/custom_components/ynab_custom).
3. Restart Home Assistant.

1. Go to Settings → Devices & Services → Integrations in Home Assistant.
2. Click "+ Add Integration" and search for "YNAB Integration for Home Assistant".
3. Enter your YNAB API Key (see below for instructions).
4. Accept terms and conditions
5. Select your budget from the dropdown/list.
6. Choose an instance_name or leave default.
7. Pick your preferred currency (USD, EUR, etc.).
8. Choose your desired update_interval or leave default (Longer intervals are better to not make too many API calls and not be rate limited).
9. Optional filters: Check boxes to include closed accounts or hidden categories (both excluded by default).
10. Select Accounts & Categories to include or leave as Select All.

1. Go to YNAB Developer Settings.
2. Click "New Token" to generate a personal access token.
3. 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.

The API Status sensor, located under the Extras device, provides comprehensive monitoring of your YNAB integration's health and API usage.

• Status (Default state value) – Current API connection status (Connected, Rate Limited, API Error, etc.)
• Last Error – Details of the most recent API error, if any
• Last Error Time – Timestamp of the last API error
• Consecutive Failures – Number of consecutive API failures
• Requests Made Total – Total API requests made across all YNAB integrations using the same token
• Requests This Hour – API requests made in the current rolling hour window
• Rate Limit Resets At – Time when the next request slot becomes available (rolling window)
• Is At Limit – Whether currently rate limited (true/false)
• Last Successful Request – Timestamp of the last successful API call

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 (true for budgeted accounts, false for 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 – true if 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!

Critical Migration & Stability Fixes:

• Fixed "Migration Error" when upgrading from v1.4.0
• Robust config entry migration with proper fallback handling
• Fixed TypeError crashes when YNAB returns null values for goal fields
• Improved update reliability - no more "Task exception was never retrieved" errors
• Enhanced logging for better troubleshooting

Filter Options (New Setups Only):

• Closed accounts and hidden categories are now excluded by default for cleaner dashboards
• Available during initial setup - delete and re-add integration to access these options

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.

• Optional Exclusion of Hidden Categories – ✅ Implemented in v1.4.1 - Toggle checkboxes now available in config flow to exclude hidden categories and closed accounts.

• Post-setup "Configure" Flow – ✅ Implemented in v1.5.0 - "Configure" button now available to change settings after initial setup without re-installing.

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!