# YNAB Amazon Categorizer
An enhanced Python package that automatically categorizes Amazon transactions in YNAB (You Need A Budget) with rich item information and automatic memo generation.
## Features
When you paste in the text from your Amazon order page:
🎯 **Smart Order Matching**: Automatically matches YNAB transactions with Amazon orders by amount and date
📝 **Enhanced Memos**: Generates detailed memos with item names and direct Amazon order links
🔄 **Intelligent Splitting**: Suggests splitting transactions with multiple items into separate categories
⚡ **Streamlined Workflow**: Smart defaults and tab completion for fast categorization
🌍 **UTF-8 Support**: Full emoji support in category names
📊 **Rich Previews**: Shows category names and transaction details before updating
## Prerequisites
- Python 3.7+
- [uv](https://docs.astral.sh/uv/) (recommended) or standard Python tooling
- YNAB account with API access
## Installation
### Method 1: Run with uvx (Recommended)
```bash
# Run directly without installing (fastest and cleanest)
uvx ynab-amazon-categorizer
```
### Method 2: Install as a tool
```bash
# Install globally with uv
uv tool install ynab-amazon-categorizer
# Then run
ynab-amazon-categorizer
```
### Method 3: Development Installation
```bash
# Clone the repository
git clone https://github.com/dizzlkheinz/ynab-amazon-categorizer.git
cd ynab-amazon-categorizer
# Install in development mode
uv pip install -e .
```
## Configuration Setup
After installation, you'll need to set up your YNAB API credentials:
### Configuration File (.env)
Create a `.env` file in your working directory with your credentials:
```
YNAB_API_KEY=your_api_key_here
YNAB_BUDGET_ID=your_budget_id_here
YNAB_ACCOUNT_ID=none
```
### Alternative: Environment Variables
```bash
# Windows
set YNAB_API_KEY=your_api_key_here
set YNAB_BUDGET_ID=your_budget_id_here
# Mac/Linux
export YNAB_API_KEY=your_api_key_here
export YNAB_BUDGET_ID=your_budget_id_here
```
## Getting Your YNAB Credentials
### API Key
1. Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer)
2. Click "New Token"
3. Copy the generated token
### Budget ID
1. Open your budget in YNAB
2. Look at the URL: `https://app.ynab.com/[budget_id]/budget`
3. Copy the budget_id part
### Account ID (Optional)
1. Click on a specific account in YNAB
2. Look at the URL: `https://app.ynab.com/[budget_id]/accounts/[account_id]`
3. Copy the account_id part (or leave as 'none' to process all accounts)
## Usage
### Basic Usage
```bash
# Run with uvx (no installation needed)
uvx ynab-amazon-categorizer
# Or if installed as a tool
ynab-amazon-categorizer
# Or run as a Python module
python -m ynab_amazon_categorizer
```
### Workflow
1. **Provide Amazon Orders Data** (optional but recommended):
- Copy your Amazon orders page content
- For example go to https://www.amazon.ca/gp/css/order-history?ref_=nav_orders_first and select all and copy the text
- Run the tool and paste Amazon order info when prompted
- The script will automatically match transactions with orders
2. **Review Matched Transactions**:
- The script shows order details, items, and links before asking to categorize
- For multiple items, it suggests splitting the transaction
3. **Categorize Transactions**:
- Use tab completion to select categories
- Accept suggested memos or customize them
- Confirm updates with enhanced previews
### Keyboard Shortcuts
- **Tab**: Auto-complete category names
- **Enter**: Accept defaults (categorize, use suggested memo, confirm update)
- **Alt+Enter**: Submit multiline input (Amazon orders data, custom memos)
- **Ctrl+C**: Cancel current operation
## Example Output
```
🎯 MATCHED ORDER FOUND:
Order ID: 702-8237239-1234567
Total: $57.57
Date: July 31, 2025
Order Link: https://www.amazon.ca/gp/your-account/order-details?ie=UTF8&orderID=702-8237239-1234567
Items:
- Fancy Feast Grilled Wet Cat Food, Tuna Feast - 85 g Can (24 Pack)
- Fancy Feast Grilled Wet Cat Food, Salmon & Shrimp Feast in Gravy - 85 g Can (24 Pack)
Action? (c = categorize/split, s = skip, q = quit, default c):
There is more than one item in this transaction.
Split this transaction? (y/n, default n): y
```
## Generated Memos
### Single Item Transaction
```
Fancy Feast Grilled Wet Cat Food, Tuna Feast - 85 g Can (24 Pack)
https://www.amazon.ca/gp/your-account/order-details?ie=UTF8&orderID=702-8237239-0563450
```
### Split Transaction Main Memo
```
2 Items:
- Fancy Feast Grilled Wet Cat Food, Tuna Feast - 85 g Can (24 Pack)
- Fancy Feast Grilled Wet Cat Food, Salmon & Shrimp Feast in Gravy - 85 g Can (24 Pack)
```
## Security Notes
⚠️ **Important**: Never commit your `.env` file to version control!
- The script loads credentials from environment variables or config file
- Your API key is never hardcoded in the script
- Add `.env` to your `.gitignore` if using git
## Troubleshooting
### "No orders could be parsed"
- Make sure you're copying the full Amazon orders page content
- Try copying from a different browser or clearing browser cache
### "API Key not found"
- Verify your `.env` file exists and has the correct format
- Check that your API key is valid in YNAB Developer Settings
### "No transactions found"
- Ensure you have uncategorized Amazon transactions in YNAB
- Check that the payee names contain "amazon", "amzn", or "amz"
### Emoji display issues
- Use `python -X utf8` on Windows for proper emoji support
- Ensure your terminal supports UTF-8 encoding
## Contributing
This package was developed to streamline YNAB Amazon transaction categorization. Feel free to suggest improvements or report issues!
## License
This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the [LICENSE](LICENSE) file for details.
Please respect YNAB's API terms of service when using this software.
Raw data
{
"_id": null,
"home_page": null,
"name": "ynab-amazon-categorizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ynab, amazon, budgeting, finance, automation",
"author": "dizzlkheinz",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/fd/65/d85f3acb46ea99e2e96e489f4f46e0dd00a1a7806ad92321dc6e1bf13988/ynab_amazon_categorizer-0.3.7.tar.gz",
"platform": null,
"description": "# YNAB Amazon Categorizer\n\nAn enhanced Python package that automatically categorizes Amazon transactions in YNAB (You Need A Budget) with rich item information and automatic memo generation.\n\n## Features\n\nWhen you paste in the text from your Amazon order page:\n\n\ud83c\udfaf **Smart Order Matching**: Automatically matches YNAB transactions with Amazon orders by amount and date \n\ud83d\udcdd **Enhanced Memos**: Generates detailed memos with item names and direct Amazon order links \n\ud83d\udd04 **Intelligent Splitting**: Suggests splitting transactions with multiple items into separate categories \n\u26a1 **Streamlined Workflow**: Smart defaults and tab completion for fast categorization \n\ud83c\udf0d **UTF-8 Support**: Full emoji support in category names \n\ud83d\udcca **Rich Previews**: Shows category names and transaction details before updating \n\n## Prerequisites\n\n- Python 3.7+\n- [uv](https://docs.astral.sh/uv/) (recommended) or standard Python tooling\n- YNAB account with API access\n\n## Installation\n\n### Method 1: Run with uvx (Recommended)\n\n```bash\n# Run directly without installing (fastest and cleanest)\nuvx ynab-amazon-categorizer\n```\n\n### Method 2: Install as a tool\n\n```bash\n# Install globally with uv\nuv tool install ynab-amazon-categorizer\n\n# Then run\nynab-amazon-categorizer\n```\n\n### Method 3: Development Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/dizzlkheinz/ynab-amazon-categorizer.git\ncd ynab-amazon-categorizer\n\n# Install in development mode\nuv pip install -e .\n```\n\n## Configuration Setup\n\nAfter installation, you'll need to set up your YNAB API credentials:\n\n### Configuration File (.env)\nCreate a `.env` file in your working directory with your credentials:\n```\nYNAB_API_KEY=your_api_key_here\nYNAB_BUDGET_ID=your_budget_id_here\nYNAB_ACCOUNT_ID=none\n```\n\n### Alternative: Environment Variables\n```bash\n# Windows\nset YNAB_API_KEY=your_api_key_here\nset YNAB_BUDGET_ID=your_budget_id_here\n\n# Mac/Linux\nexport YNAB_API_KEY=your_api_key_here\nexport YNAB_BUDGET_ID=your_budget_id_here\n```\n\n## Getting Your YNAB Credentials\n\n### API Key\n1. Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer)\n2. Click \"New Token\"\n3. Copy the generated token\n\n### Budget ID\n1. Open your budget in YNAB\n2. Look at the URL: `https://app.ynab.com/[budget_id]/budget`\n3. Copy the budget_id part\n\n### Account ID (Optional)\n1. Click on a specific account in YNAB\n2. Look at the URL: `https://app.ynab.com/[budget_id]/accounts/[account_id]`\n3. Copy the account_id part (or leave as 'none' to process all accounts)\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Run with uvx (no installation needed)\nuvx ynab-amazon-categorizer\n\n# Or if installed as a tool\nynab-amazon-categorizer\n\n# Or run as a Python module\npython -m ynab_amazon_categorizer\n```\n\n### Workflow\n1. **Provide Amazon Orders Data** (optional but recommended):\n - Copy your Amazon orders page content\n - For example go to https://www.amazon.ca/gp/css/order-history?ref_=nav_orders_first and select all and copy the text\n - Run the tool and paste Amazon order info when prompted \n - The script will automatically match transactions with orders\n\n2. **Review Matched Transactions**:\n - The script shows order details, items, and links before asking to categorize\n - For multiple items, it suggests splitting the transaction\n\n3. **Categorize Transactions**:\n - Use tab completion to select categories\n - Accept suggested memos or customize them\n - Confirm updates with enhanced previews\n\n### Keyboard Shortcuts\n- **Tab**: Auto-complete category names\n- **Enter**: Accept defaults (categorize, use suggested memo, confirm update)\n- **Alt+Enter**: Submit multiline input (Amazon orders data, custom memos)\n- **Ctrl+C**: Cancel current operation\n\n## Example Output\n\n```\n\ud83c\udfaf MATCHED ORDER FOUND:\n Order ID: 702-8237239-1234567\n Total: $57.57\n Date: July 31, 2025\n Order Link: https://www.amazon.ca/gp/your-account/order-details?ie=UTF8&orderID=702-8237239-1234567\n Items:\n - Fancy Feast Grilled Wet Cat Food, Tuna Feast - 85 g Can (24 Pack)\n - Fancy Feast Grilled Wet Cat Food, Salmon & Shrimp Feast in Gravy - 85 g Can (24 Pack)\n\nAction? (c = categorize/split, s = skip, q = quit, default c): \nThere is more than one item in this transaction.\nSplit this transaction? (y/n, default n): y\n```\n\n## Generated Memos\n\n### Single Item Transaction\n```\nFancy Feast Grilled Wet Cat Food, Tuna Feast - 85 g Can (24 Pack)\n https://www.amazon.ca/gp/your-account/order-details?ie=UTF8&orderID=702-8237239-0563450\n```\n\n### Split Transaction Main Memo\n```\n2 Items:\n- Fancy Feast Grilled Wet Cat Food, Tuna Feast - 85 g Can (24 Pack)\n- Fancy Feast Grilled Wet Cat Food, Salmon & Shrimp Feast in Gravy - 85 g Can (24 Pack)\n```\n\n## Security Notes\n\n\u26a0\ufe0f **Important**: Never commit your `.env` file to version control!\n\n- The script loads credentials from environment variables or config file\n- Your API key is never hardcoded in the script\n- Add `.env` to your `.gitignore` if using git\n\n## Troubleshooting\n\n### \"No orders could be parsed\"\n- Make sure you're copying the full Amazon orders page content\n- Try copying from a different browser or clearing browser cache\n\n### \"API Key not found\"\n- Verify your `.env` file exists and has the correct format\n- Check that your API key is valid in YNAB Developer Settings\n\n### \"No transactions found\"\n- Ensure you have uncategorized Amazon transactions in YNAB\n- Check that the payee names contain \"amazon\", \"amzn\", or \"amz\"\n\n### Emoji display issues\n- Use `python -X utf8` on Windows for proper emoji support\n- Ensure your terminal supports UTF-8 encoding\n\n## Contributing\n\nThis package was developed to streamline YNAB Amazon transaction categorization. Feel free to suggest improvements or report issues!\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the [LICENSE](LICENSE) file for details.\n\nPlease respect YNAB's API terms of service when using this software.\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Automatically categorize Amazon transactions in YNAB with rich item information",
"version": "0.3.7",
"project_urls": {
"Homepage": "https://github.com/dizzlkheinz/ynab-amazon-categorizer",
"Issues": "https://github.com/dizzlkheinz/ynab-amazon-categorizer/issues",
"Repository": "https://github.com/dizzlkheinz/ynab-amazon-categorizer"
},
"split_keywords": [
"ynab",
" amazon",
" budgeting",
" finance",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e116c2a75868afc5c6e2a75b4fb41ebe51fbc7730b9bda26e4d1fa10d7cd5acc",
"md5": "8c967bbc6e19b8627477d0ba9871c0a0",
"sha256": "dd7bb11e25d7c25044c47f3d66541649de9e61006dcff8999c8ee975c3c6f5e7"
},
"downloads": -1,
"filename": "ynab_amazon_categorizer-0.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c967bbc6e19b8627477d0ba9871c0a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 27901,
"upload_time": "2025-09-12T21:54:17",
"upload_time_iso_8601": "2025-09-12T21:54:17.425355Z",
"url": "https://files.pythonhosted.org/packages/e1/16/c2a75868afc5c6e2a75b4fb41ebe51fbc7730b9bda26e4d1fa10d7cd5acc/ynab_amazon_categorizer-0.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fd65d85f3acb46ea99e2e96e489f4f46e0dd00a1a7806ad92321dc6e1bf13988",
"md5": "7141d76ad0976fa59de420a9a7879b84",
"sha256": "11a063be7f4a9bf4f09bf6c56ecb5c5c7fc999b1071bb177d01a8eb9cc4e2255"
},
"downloads": -1,
"filename": "ynab_amazon_categorizer-0.3.7.tar.gz",
"has_sig": false,
"md5_digest": "7141d76ad0976fa59de420a9a7879b84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 45164,
"upload_time": "2025-09-12T21:54:18",
"upload_time_iso_8601": "2025-09-12T21:54:18.846104Z",
"url": "https://files.pythonhosted.org/packages/fd/65/d85f3acb46ea99e2e96e489f4f46e0dd00a1a7806ad92321dc6e1bf13988/ynab_amazon_categorizer-0.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 21:54:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dizzlkheinz",
"github_project": "ynab-amazon-categorizer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ynab-amazon-categorizer"
}
JSON
