YNAB Budget Management

Manage your YNAB budget via the API with ready-to-use bash scripts. Requires curl and jq.

Configuration

Set environment variables YNAB_API_KEY and YNAB_BUDGET_ID, or create ~/.config/ynab/config.json:

{
  "api_key": "YOUR_YNAB_TOKEN",
  "budget_id": "YOUR_BUDGET_ID",
  "monthly_target": 2000
}

The monthly_target field sets your monthly spending cap (used by daily-spending-report.sh). Can also be set via YNAB_MONTHLY_TARGET env var.

Get your token at https://app.ynab.com/settings/developer. Find your Budget ID in the YNAB URL.

Available Scripts

All scripts are in {baseDir}/scripts/ and output to stdout.

Key API Concepts

Amounts use milliunits

YNAB API represents all amounts in milliunits: 10.00 = 10000, -10.00 = -10000. Always divide by 1000 when displaying, multiply by 1000 when submitting.

Always categorize transactions

Never create transactions without a category -- it breaks budget tracking. When encountering an unfamiliar merchant, search past transactions for the same payee and reuse the category for consistency.

Check for pending transactions before adding

Before creating a new transaction, check if an unapproved one already exists for the same amount. If found, approve it instead. This avoids duplicates from bank imports.

Transfers require transfer_payee_id

To create a real linked transfer between accounts, use the destination account's transfer_payee_id (not payee_name). Using payee_name creates a regular transaction that YNAB won't recognize as a transfer. See references/api-guide.md for the full transfer guide.

Split transactions

Transactions with category "Split" contain subtransactions. Always expand them to show subcategories in reports -- never show "Split" as a category name.

Common API Operations

YNAB_API="https://api.ynab.com/v1"

# Add a transaction
# POST \/budgets/\/transactions
# Body: {"transaction": {"account_id": "UUID", "date": "2026-03-06", "amount": -10000, "payee_name": "Coffee Shop", "category_id": "UUID", "approved": true}}

# Search transactions by payee
# GET \/budgets/\/transactions | jq filter by payee_name

# List categories
# GET \/budgets/\/categories

For the complete transfer guide, monthly spending calculation, and account ID management, see references/api-guide.md. For category naming examples, see references/category-examples.md.

Agent Guidance

• Always categorize at transaction creation time -- searching past transactions for the same payee is the best way to find the right category.
• For transfers, always use transfer_payee_id from the destination account. Using payee_name is a common mistake that creates a regular expense instead.
• When calculating monthly spending, only count amount < 0 and exclude transfers (transfer_account_id != null). Transfers are internal money movements, not expenses.
• Rate limit is ~200 requests/hour. Cache account and category data when doing bulk operations. In caso di errore API (401, 429, 5xx), riprovare silenziosamente 2-3 volte con pausa di 10-15s prima di segnalare qualsiasi problema all'utente. MAI dichiarare che la chiave API è scaduta al primo errore 401 — è quasi sempre un rate limit temporaneo.
• Never log or display full API keys in output.
• When running daily-spending-report.sh, the script outputs an "ANALYSIS DATA" section with raw metrics. Reinterpret this data in your own voice and style — give the user a brief, natural-language comment on their spending pace, highlight anything noteworthy, and mention the daily budget figure.

Troubleshooting

• 401 Unauthorized: ⚠️ NON assumere subito che la chiave sia scaduta! Spesso un 401 è causato da un rate limit temporaneo (l'API YNAB a volte restituisce 401 invece di 429 quando si supera il limite). Prima azione: aspettare 10-15 secondi e riprovare. Solo se il 401 persiste dopo 2-3 tentativi con pausa, allora la chiave potrebbe essere effettivamente scaduta. Mai dire all'utente di rigenerare il token come prima risposta.
• 404 Not Found: Budget ID wrong -- check the YNAB URL
• 429 Too Many Requests: Rate limit -- add delays between bulk calls. Aspettare 15-30 secondi prima di riprovare.
• Transfer not linking: Using payee_name instead of transfer_payee_id
• Errori HTTP intermittenti: In caso di qualsiasi errore API, riprovare almeno 2 volte con pausa di 10s prima di segnalare il problema all'utente.

API docs: https://api.ynab.com