YNAB

YNAB

YNAB organizes finances by plan (the product UI still says "budget"). Every data read is plan-scoped except the authenticated user profile check.

Recommended read order

1. Confirm the connection with the user profile read.
2. List plans — response includes default_scope.plan_id when one plan is accessible or a default is saved on the credential.
3. Plan-scoped reads — omit plan_id when a default is saved, cached, or last-used applies.

Default plan resolution

Plan-scoped tools accept an optional plan_id. When omitted, resolution order is:

1. Saved Default Plan on the connection (FIELDS token setup or OAuth additional field).
2. Cached default_scope.plan_id from the latest plan listing call.
3. Single accessible plan auto-selected after discovery.
4. Fallback: last-used (YNAB's most recently opened plan).

Re-list plans after linking a new plan or changing defaults.

Data model

• Plans — top-level container; accounts, categories, payees, and transactions belong to a plan.
• Accounts — on-budget or tracking; every transaction belongs to an account.
• Category groups & categories — envelope buckets; category reads return groups with nested categories (YNAB has no separate category-group read endpoint).
• Payees — merchants and transfer payees (transfer_account_id marks account transfers).
• Transactions — amounts are in milliunits; use transaction listing with date or entity filters.
• Months — Ready to Assign, Age of Money, and month-scoped category amounts.
• Scheduled transactions — upcoming/recurring rows not yet entered.

Write workflows

• Assign money — update category budget with category_id, month (current works), and budgeted milliunits.
• Log spending — create or update transactions (account_id, date, amount to create; transaction_id to update).
• Payees — create or rename payees.
• Scheduled rules — create, update, or delete scheduled transactions.
• Bank import — trigger linked-account import for a plan.

Write tools require a Personal Access Token or OAuth without the read-only scope. Existing read-only OAuth connections can still read but get a clear error on writes.

Gotchas

• plan_id optional on plan-scoped tools when a default is saved or discoverable. Magic values: last-used, default.
• Milliunits: divide amounts by 1000 for currency display ($12.34 → 12340).
• Category amounts on list endpoints reflect the current plan month (UTC). Pass month on category reads for a specific month.
• Empty plans list means the authorized YNAB account has no plans yet; downstream steps cannot run without a plan id.