YNAB Amazon Helper

Automatically link your YNAB transactions to Amazon orders and categorize them using AI.

Features

• Unapproved Transaction Workflow: Automatically fetch and match only unapproved YNAB transactions (no date range needed!)
• Automated Matching: Matches YNAB transactions with Amazon orders based on amount and date proximity
• Web Scraping: Scrapes your Amazon order history using Puppeteer (no Amazon API keys required)
• AI-Powered Categorization: Uses OpenAI to suggest appropriate YNAB categories based on product descriptions
• Visual Review Interface: Web UI to review, approve, and modify matches before applying
• Batch Updates: Apply approved matches to YNAB with one click, automatically marking them as approved

Prerequisites

• Bun runtime installed
• YNAB account with API access
• Amazon account
• OpenAI API key

Setup

1. Install Dependencies

bun install

2. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and fill in your credentials:

# YNAB API Configuration
YNAB_API_TOKEN=your_ynab_personal_access_token
YNAB_BUDGET_ID=your_budget_id

# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key

# Server Configuration
PORT=3000
NODE_ENV=development

Note: Amazon credentials are NOT required. You'll log in manually through the browser when scraping.

3. Get Your YNAB API Token

1. Go to YNAB Account Settings
2. Navigate to "Developer Settings"
3. Click "New Token" and copy the personal access token
4. To find your Budget ID, you can use the YNAB API or check the URL when viewing your budget

4. Get Your OpenAI API Key

1. Go to OpenAI API Keys
2. Create a new secret key
3. Copy the key (you won't be able to see it again)

Usage

Start the Server

bun --hot server.ts

The server will start at http://localhost:3000

Using the Application

1. Open the Web Interface: Navigate to http://localhost:3000 in your browser

2. Choose Transaction Mode:

   • Unapproved Transactions (Recommended): Automatically fetches all unapproved transactions from YNAB
   • Date Range: Manually specify start and end dates for transactions to match

3. Fetch Matches: Click "Fetch & Match Transactions"

   • The app will fetch YNAB transactions (unapproved or by date range)
   • Scrape Amazon orders from the relevant time period (opens a browser window)
   • Match transactions using date/amount proximity
   • Suggest categories using AI

4. Review Matches:

   • Each match shows the YNAB transaction and corresponding Amazon order
   • Confidence scores help identify quality matches
   • Review AI-suggested categories and modify if needed
   • Approve or reject each match

5. Apply Changes: Click "Apply Approved Matches" to update YNAB

   • Amazon order links will be added to transaction memos
   • Categories will be updated if changed
   • Transactions will be marked as approved

How It Works

Transaction Matching Algorithm

The matcher uses a scoring system based on:

• Amount Matching (50% weight): Compares transaction amount with order total
• Date Proximity (30% weight): Considers orders within ±3 days of transaction
• Payee Name (20% weight): Boosts score for Amazon-related payees

Default tolerances:

• Date: ±3 days
• Amount: ±$0.50

AI Categorization

OpenAI analyzes product descriptions and suggests categories from your YNAB budget:

• Uses GPT-4o-mini for cost efficiency
• Considers all items in multi-item orders
• Maps products to your existing category structure

Amazon Scraping

The scraper:

• Uses Puppeteer to automate browser interactions
• Navigates to Amazon transactions page (https://www.amazon.com/cpe/yourpayments/transactions)
• Automatically logs into your Amazon account if needed
• Extracts transaction details, dates, and amounts
• Caches session data to avoid repeated logins
• Takes debug screenshots for troubleshooting

Important Notes:

• A browser window will open and navigate to the Amazon transactions page
• You'll need to log in manually - the app waits 45 seconds for you to complete login
• Once logged in, the session is cached in .puppeteer_cache/ for future runs
• If you're already logged in (from a previous session), scraping will start automatically
• Debug screenshots are saved to debug-transactions-page.png for troubleshooting

Project Structure

├── server.ts              # Bun.serve backend API
├── index.html            # Main HTML page
├── frontend.tsx          # Frontend TypeScript/React
├── types.ts              # TypeScript type definitions
├── amazon-scraper.ts     # Amazon order scraping logic
├── ynab-client.ts        # YNAB API integration
├── matcher.ts            # Transaction matching algorithm
├── category-suggester.ts # OpenAI category suggestions
└── .env                  # Environment configuration (not in git)

API Endpoints

• GET / - Serve web interface
• POST /api/fetch-matches - Fetch and match transactions
• GET /api/matches/:sessionId - Get matches for a session
• PATCH /api/matches/:sessionId/:matchIndex - Update match status
• POST /api/approve-matches/:sessionId - Apply approved matches to YNAB
• GET /api/categories - Get YNAB categories

Troubleshooting

Amazon Login Issues

• 2FA Required: Complete 2FA manually when the browser opens
• CAPTCHA: Solve any CAPTCHA challenges that appear
• Session Expired: Delete .puppeteer_cache/ and try again

YNAB API Issues

• Invalid Token: Regenerate your personal access token
• Budget Not Found: Verify your budget ID is correct
• Rate Limits: The app respects YNAB rate limits automatically

OpenAI Issues

• Rate Limits: Categories are suggested in batches with delays
• Cost Concerns: Uses gpt-4o-mini (~$0.15 per 1M tokens)
• Poor Suggestions: Review and manually select correct categories

Security Considerations

• Never commit .env file to version control
• Amazon credentials are stored locally only
• YNAB token has read/write access to your budget
• Puppeteer cache may contain session cookies

Future Enhancements

• Support for multiple budgets
• Database for persistent match storage
• Manual order entry (for non-Amazon purchases)
• Improved scraping with stealth plugins
• Export/import match history
• Category learning from past matches

License

MIT

Built With

• Bun - Fast JavaScript runtime
• Puppeteer - Headless browser automation
• YNAB API - Budget data integration
• OpenAI API - AI categorization