YNAB API Technical Reference

Configuration

Authentication Setup

• Personal Tokens (5-minute setup): Generate at YNAB settings, never expires
• OAuth 2.0 (30-minute setup): Required for multi-user apps, starts with 25-user limit until manual approval
• Base URL: https://api.ynab.com/v1
• Response Format: JSON wrapped in data object

Rate Limits

• Limit: 200 requests/hour (rolling window)
• Failure Mode: 429 error when exceeded
• Development Impact: Easy to hit during debugging (10-minute cycles)
• Mitigation: Use delta sync and response caching

Critical Warnings

Milliunits Conversion

• Format: All currency amounts multiplied by 1000
• Example: $50.00 = 50000 milliunits
• Reason: Prevents JavaScript floating-point calculation errors
• Production Failure: Forgetting conversion shows amounts 1000x too large

Subscription Dependencies

• Requirement: Active YNAB subscription ($109/year as of 2025)
• Failure Mode: Immediate 403 errors when subscription lapses
• Error Response: "subscription_lapsed" in error message
• Impact: Users assume app is broken, not subscription issue

Date Format Requirements

• Format: ISO format (YYYY-MM-DD) only
• Failure Mode: Transactions fail silently with incorrect dates
• Library Recommendation: Use date-fns (Moment.js deprecated)

Resource Requirements

Time Investment

• Personal Token Setup: 5 minutes
• OAuth Implementation: 2 hours including testing
• API Debugging: Rate limit hits cause frequent delays

Expertise Requirements

• Basic REST API knowledge: Standard JSON responses
• Financial data handling: Understanding of milliunits conversion
• Error handling: YNAB provides useful error messages (not generic 500s)

Technical Specifications

API Capabilities

• CRUD Operations: Full create, read, update, delete on transactions
• Data Access: Budgets, accounts, categories, transactions, payees
• Limitation: Cannot delete categories via API (manual YNAB action required)
• Delta Sync: Returns only changed data since last request

Performance Thresholds

• Rate Limit: 200/hour sufficient for most personal projects
• Polling Frequency: Every 5 minutes approaches rate limit danger
• Response Headers: Include remaining request count

Official SDKs

• JavaScript (npm): Browser + Node.js, TypeScript definitions
• Ruby (gem): Auto-handles auth headers
• Python (PyPI): Python 3.8+ required

Decision Criteria

YNAB API vs Alternatives

Criteria	YNAB API	PocketSmith API	Tiller
Setup Complexity	Personal tokens: 5 min OAuth: 30 min	OAuth-only: 30+ min	Google Sheets auth: 2+ hours
Write Capabilities	Full CRUD	Read-only	Complex spreadsheet writes
Cost	$109/year (need YNAB)	$10-19/month	$79/year
Bank Connections	Sync for YNAB (EU focus)	Global coverage	Manual/scripted
Best For	Existing YNAB users	Multi-currency needs	Spreadsheet flexibility

When to Choose YNAB API

• Already using YNAB for budgeting
• Need automation of budget data
• Building personal finance tools
• Prefer zero-based budgeting methodology

When to Avoid

• Need multi-currency support
• Require real-time webhooks (polling only)
• Building for non-YNAB users

Common Failure Scenarios

Development Issues

• Rate Limit Debugging: Hitting 200/hour during development cycles
• Milliunit Display: Amounts appear 1000x larger in UI
• Silent Transaction Failures: Incorrect date formats cause no error messages
• Category Management: Cannot delete categories programmatically

Production Failures

• Subscription Lapses: Immediate API access loss, users blame app
• Date Format Errors: Half of transaction imports fail randomly
• Authentication Errors: 401 responses indicate wrong token format

Testing and Validation

Debug Tools

• Interactive Docs: api.ynab.com/v1 with built-in testing
• Error Messages: Specific, actionable error descriptions
• Status Monitoring: ynabstatus.com for API health

Test Command

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.ynab.com/v1/budgets"

• Success: JSON with budget data
• Failure: 401 indicates token issues

Community Resources

Actively Maintained Tools

• Sync for YNAB: European bank import
• Bank2YNAB: US bank CSV converter
• Toolkit for YNAB: Browser extension for missing features

Quality Indicators

• Official SDKs: Reliable, regularly updated
• Community Libraries: Variable quality, check maintenance status
• Third-party Apps: 30+ in official showcase, most are demos or abandoned

Implementation Guidance

Best Practices

• Use delta sync to minimize requests
• Cache API responses during development
• Handle subscription lapse errors gracefully
• Convert milliunits for display (divide by 1000)
• Use official SDKs instead of raw HTTP calls

Avoid These Mistakes

• Polling every few minutes (rate limit risk)
• Displaying raw milliunit values
• Assuming categories can be deleted via API
• Using deprecated date libraries (Moment.js)
• Building OAuth when personal tokens suffice