# Mint Transactions Tagger for Amazon Purchases
## UPDATE - Now works with Amazon "Request My Data" Export ##
This tool originally worked with the "Order History Reports", which gave one slice of information about Amazon order history. Amazon sunset this export/reporting tool on 3/20/2023. I have since adapted this tool to work with the zipfile of data produced by that slower, cumbersome, and more comprehensive "Request My Data" tool - for details on this migration, see
[this issue](https://github.com/jprouty/mint-amazon-tagger/issues/151).
The most important change is that category information is not present in this export, meaning the tool cannot help you categorize never before seen items. For previously purchased items, by default the tool use the most common tagged category, based on an exact string match of the line item description.
## Overview ##
Do you order a lot from Amazon? Tired of everything showing up as "Amazon"
and category "Shopping" in mint.com? Then this tool is for you!
This tool takes an Amazon "Request your data" Order export and matches
your Amazon order history with your Mint transactions. If it finds an exact matches
it will either:
- Update the transaction description and category if there was only 1 item
- Itemize the transaction - one line-item per item in the order (via Mint transaction splits)
If the tool chooses poor categories for your transactions simply change it! The next time you run the tool it will remember your past personalized category edits and attempt to apply it to future purchases of the same
item. This only works if the item names match exactly. Also, you must
change all (or the majority of) all the past, tagged examples of that item for the tool to pick up the hint. Put another way: if you only change 1 past transaction and you have 10 purchases of that same item the tool will take whatever the most common category used for that item.
This tool **will not** retag or touch transactions that have already been
tagged. Feel free to adjust categories after the fact without fear that the
next run will wipe everything out. If you do want to re-tag
previously tagged transactions take a look at the retag_changed option.
This tool **does not** save your username or password. The tool is powered by the [Selenium framework](https://www.selenium.dev/) to automate an instance of the Chrome/Chromium browser. When running the tool it will prompt for the username and password and then enter it into the browser for you. There are options that allow for manual user operation of the login flows for both Mint and Amazon.
This tool **does not** require an Amazon store card/Visa. All you need is to pay for your Amazon charges with an account that is synchronized with Mint. For example, if you alternate between 5 different credit cards to pay for purchases on your Amazon account, only the transactions from credit cards synchronized with Mint will get tagged.
Some things the tagger cannot do:
- Amazon credit card award points are not reported anywhere in the order/item reports.
- Amazon gift cards are not yet supported (see [issue #59](https://github.com/jprouty/mint-amazon-tagger/issues/59))
## Sponsorship ##
This project has been a passion project of [mine](https://github.com/jprouty) to better understand cashflow (critical to trend analysis and budgeting).
If you have found this tool useful, please consider [sponsoring me](https://github.com/sponsors/jprouty).
## Install and Getting started ##
### EASIEST - Pre-built binaries ###
Please download the latest version from [github's releases page](https://github.com/jprouty/mint-amazon-tagger/releases)
### ADVANCED - Docker Headless CLI ###
You can run the Mint Amazon Tagger via docker like so:
```
# Check out this git repo if not already:
git clone https://github.com/jprouty/mint-amazon-tagger.git
cd mint-amazon-tagger
# Build the image:
docker build -t mint-amazon-tagger .
# Run the container:
docker run -it --rm mint-amazon-tagger
```
If you're using ARM, you need to build with:
```
docker build --platform linux/amd64 -t mint-amazon-tagger .
```
### ADVANCED - Run from python source ###
#### Setup ####
1. `pip3 install mint-amazon-tagger`
2. To get the latest from time to time, update your version:
`pip3 install --upgrade mint-amazon-tagger`
3. Chromedriver should be fetched automatically. But if you run into issues,
try this:
```
# Mac:
brew tap homebrew/cask
brew cask install chromedriver
# Ubuntu/Debian:
# See also: https://askubuntu.com/questions/539498/where-does-chromedriver-install-to
sudo apt-get install chromium-chromedriver
```
#### Running - Full Auto GUI ####
This mode will fetch your Amazon Order History for you as well as tag mint.
1. `mint-amazon-tagger`
1. Plug in all your info into the app!
#### Running - Full Auto CLI ####
This mode will fetch your Amazon Order History for you as well as tag mint.
1. `mint-amazon-tagger-cli --amazon_email email@cool.com --mint_email couldbedifferent@aol.com`
#### Running - Semi-Auto ####
This mode requires you to fetch your Amazon Order History manually, then the
tagger automates the rest.
1. Generate and download your Amazon Order History Reports.
a. Login and visit [Amazon Order History
Reports](https://www.amazon.com/gp/b2b/reports)
b. "Request Report" for "Items", "charges and shipments", and "Refunds". Make sure the
date ranges are the same.
c. Download the completed reports. Let's called them
`Items.csv charges.csv Refunds.csv` for this walk-through. Note that
Refunds is optional! Yay.
2. (Optional) Do a dry run! Make sure everything looks right first. Run:
`mint-amazon-tagger-cli --items_csv Items.csv --charges_csv charges.csv --refunds_csv Refunds.csv --dry_run --mint_email yourEmail@here.com`
3. Now perform the actual updates, without `--dry_run`:
`mint-amazon-tagger-cli --items_csv Items.csv --charges_csv charges.csv --refunds_csv Refunds.csv --mint_email yourEmail@here.com`
4. Sit back and relax! The run time depends on the speed of your machine,
quality of internet connection, and total number of transactions. For
reference, my machine did about 14k Mint transactions, finding 2k Amazon
matches in under 10 minutes.
To see all options, see:
`mint-amazon-tagger-cli --help`
## Tips and Tricks ##
Not every bank treats Amazon purchases the same, or processes transactions as quickly as others. If you are having a low match rate (look at the terminal output after completion), then try adjusting some of the options or command line flags. To see a complete list, run `mint-amazon-tagger-cli --help`.
Some common options to try:
- --mint_input_include_inferred_description. This allows for more generous consideration of Mint transactions for matching. See [more context here](https://github.com/jprouty/mint-amazon-tagger/issues/50)
- --mint_input_include_user_description. Similar to above; considers the current description as shown in the Mint tool (including any user edits).
- --max_days_between_payment_and_shipping. If your bank is slow at posting payments, adjusting this value up to 7 or more will increase your chance of matching. If you have a high volume of purchases, this can increase your chance of mis-tagging items.
Raw data
{
"_id": null,
"home_page": "https://github.com/jprouty/mint-amazon-tagger",
"name": "mint-amazon-tagger",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "amazon mint tagger transactions order history",
"author": "Jeff Prouty",
"author_email": "jeff.prouty@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/96/02/72ea8747f6600924be1dacb95334851cfc97aa9d46984d9c513d2e6df663/mint-amazon-tagger-1.66.tar.gz",
"platform": null,
"description": "# Mint Transactions Tagger for Amazon Purchases\n\n## UPDATE - Now works with Amazon \"Request My Data\" Export ##\n\nThis tool originally worked with the \"Order History Reports\", which gave one slice of information about Amazon order history. Amazon sunset this export/reporting tool on 3/20/2023. I have since adapted this tool to work with the zipfile of data produced by that slower, cumbersome, and more comprehensive \"Request My Data\" tool - for details on this migration, see \n[this issue](https://github.com/jprouty/mint-amazon-tagger/issues/151).\n\nThe most important change is that category information is not present in this export, meaning the tool cannot help you categorize never before seen items. For previously purchased items, by default the tool use the most common tagged category, based on an exact string match of the line item description.\n\n## Overview ##\n\nDo you order a lot from Amazon? Tired of everything showing up as \"Amazon\"\nand category \"Shopping\" in mint.com? Then this tool is for you!\n\nThis tool takes an Amazon \"Request your data\" Order export and matches\nyour Amazon order history with your Mint transactions. If it finds an exact matches\nit will either:\n\n- Update the transaction description and category if there was only 1 item\n- Itemize the transaction - one line-item per item in the order (via Mint transaction splits)\n\nIf the tool chooses poor categories for your transactions simply change it! The next time you run the tool it will remember your past personalized category edits and attempt to apply it to future purchases of the same\nitem. This only works if the item names match exactly. Also, you must\nchange all (or the majority of) all the past, tagged examples of that item for the tool to pick up the hint. Put another way: if you only change 1 past transaction and you have 10 purchases of that same item the tool will take whatever the most common category used for that item.\n\nThis tool **will not** retag or touch transactions that have already been\ntagged. Feel free to adjust categories after the fact without fear that the\nnext run will wipe everything out. If you do want to re-tag\npreviously tagged transactions take a look at the retag_changed option.\n\nThis tool **does not** save your username or password. The tool is powered by the [Selenium framework](https://www.selenium.dev/) to automate an instance of the Chrome/Chromium browser. When running the tool it will prompt for the username and password and then enter it into the browser for you. There are options that allow for manual user operation of the login flows for both Mint and Amazon.\n\nThis tool **does not** require an Amazon store card/Visa. All you need is to pay for your Amazon charges with an account that is synchronized with Mint. For example, if you alternate between 5 different credit cards to pay for purchases on your Amazon account, only the transactions from credit cards synchronized with Mint will get tagged.\n\nSome things the tagger cannot do:\n\n- Amazon credit card award points are not reported anywhere in the order/item reports.\n- Amazon gift cards are not yet supported (see [issue #59](https://github.com/jprouty/mint-amazon-tagger/issues/59))\n\n## Sponsorship ##\n\nThis project has been a passion project of [mine](https://github.com/jprouty) to better understand cashflow (critical to trend analysis and budgeting).\n\nIf you have found this tool useful, please consider [sponsoring me](https://github.com/sponsors/jprouty).\n\n## Install and Getting started ##\n\n### EASIEST - Pre-built binaries ###\n\nPlease download the latest version from [github's releases page](https://github.com/jprouty/mint-amazon-tagger/releases)\n\n### ADVANCED - Docker Headless CLI ###\n\nYou can run the Mint Amazon Tagger via docker like so:\n\n```\n# Check out this git repo if not already:\ngit clone https://github.com/jprouty/mint-amazon-tagger.git\ncd mint-amazon-tagger\n\n# Build the image:\ndocker build -t mint-amazon-tagger .\n\n# Run the container:\ndocker run -it --rm mint-amazon-tagger\n```\n\nIf you're using ARM, you need to build with:\n\n```\ndocker build --platform linux/amd64 -t mint-amazon-tagger .\n```\n\n### ADVANCED - Run from python source ###\n\n#### Setup ####\n\n1. `pip3 install mint-amazon-tagger`\n\n2. To get the latest from time to time, update your version:\n`pip3 install --upgrade mint-amazon-tagger`\n\n3. Chromedriver should be fetched automatically. But if you run into issues,\ntry this:\n\n```\n# Mac:\nbrew tap homebrew/cask\nbrew cask install chromedriver\n\n# Ubuntu/Debian:\n# See also: https://askubuntu.com/questions/539498/where-does-chromedriver-install-to\nsudo apt-get install chromium-chromedriver\n```\n\n#### Running - Full Auto GUI ####\n\nThis mode will fetch your Amazon Order History for you as well as tag mint.\n\n1. `mint-amazon-tagger`\n\n1. Plug in all your info into the app!\n\n#### Running - Full Auto CLI ####\n\nThis mode will fetch your Amazon Order History for you as well as tag mint.\n\n1. `mint-amazon-tagger-cli --amazon_email email@cool.com --mint_email couldbedifferent@aol.com`\n\n#### Running - Semi-Auto ####\n\nThis mode requires you to fetch your Amazon Order History manually, then the\ntagger automates the rest.\n\n1. Generate and download your Amazon Order History Reports.\n\na. Login and visit [Amazon Order History\nReports](https://www.amazon.com/gp/b2b/reports)\n\nb. \"Request Report\" for \"Items\", \"charges and shipments\", and \"Refunds\". Make sure the\ndate ranges are the same.\n\nc. Download the completed reports. Let's called them\n`Items.csv charges.csv Refunds.csv` for this walk-through. Note that\nRefunds is optional! Yay.\n\n2. (Optional) Do a dry run! Make sure everything looks right first. Run:\n`mint-amazon-tagger-cli --items_csv Items.csv --charges_csv charges.csv --refunds_csv Refunds.csv --dry_run --mint_email yourEmail@here.com`\n\n3. Now perform the actual updates, without `--dry_run`:\n`mint-amazon-tagger-cli --items_csv Items.csv --charges_csv charges.csv --refunds_csv Refunds.csv --mint_email yourEmail@here.com`\n\n4. Sit back and relax! The run time depends on the speed of your machine,\nquality of internet connection, and total number of transactions. For\nreference, my machine did about 14k Mint transactions, finding 2k Amazon\nmatches in under 10 minutes.\n\nTo see all options, see:\n`mint-amazon-tagger-cli --help`\n\n## Tips and Tricks ##\n\nNot every bank treats Amazon purchases the same, or processes transactions as quickly as others. If you are having a low match rate (look at the terminal output after completion), then try adjusting some of the options or command line flags. To see a complete list, run `mint-amazon-tagger-cli --help`.\n\nSome common options to try:\n\n- --mint_input_include_inferred_description. This allows for more generous consideration of Mint transactions for matching. See [more context here](https://github.com/jprouty/mint-amazon-tagger/issues/50)\n- --mint_input_include_user_description. Similar to above; considers the current description as shown in the Mint tool (including any user edits).\n- --max_days_between_payment_and_shipping. If your bank is slow at posting payments, adjusting this value up to 7 or more will increase your chance of matching. If you have a high volume of purchases, this can increase your chance of mis-tagging items.\n",
"bugtrack_url": null,
"license": "",
"summary": "Fetches your Amazon order history and matching/tags your Mint transactions",
"version": "1.66",
"project_urls": {
"Homepage": "https://github.com/jprouty/mint-amazon-tagger"
},
"split_keywords": [
"amazon",
"mint",
"tagger",
"transactions",
"order",
"history"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca4358c1004c3eed217e5f58925e2daf794ef362cf43d75da2d3f316715e820c",
"md5": "13bbdce725aaa786803eebba8a1f61b9",
"sha256": "af150f4e8b2f81fbb058c72f99272842b3b01c6edc4cc7fec0c860aaa47054a1"
},
"downloads": -1,
"filename": "mint_amazon_tagger-1.66-py3-none-any.whl",
"has_sig": false,
"md5_digest": "13bbdce725aaa786803eebba8a1f61b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 114906,
"upload_time": "2024-01-01T19:30:27",
"upload_time_iso_8601": "2024-01-01T19:30:27.784639Z",
"url": "https://files.pythonhosted.org/packages/ca/43/58c1004c3eed217e5f58925e2daf794ef362cf43d75da2d3f316715e820c/mint_amazon_tagger-1.66-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "960272ea8747f6600924be1dacb95334851cfc97aa9d46984d9c513d2e6df663",
"md5": "0a8cf16703c54f1febba41b9fce77dac",
"sha256": "3ff1dea9865fa11801b521215cbeb16b0a63c10b31fb606b6de321934d57ab22"
},
"downloads": -1,
"filename": "mint-amazon-tagger-1.66.tar.gz",
"has_sig": false,
"md5_digest": "0a8cf16703c54f1febba41b9fce77dac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 107434,
"upload_time": "2024-01-01T19:30:30",
"upload_time_iso_8601": "2024-01-01T19:30:30.159298Z",
"url": "https://files.pythonhosted.org/packages/96/02/72ea8747f6600924be1dacb95334851cfc97aa9d46984d9c513d2e6df663/mint-amazon-tagger-1.66.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-01 19:30:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jprouty",
"github_project": "mint-amazon-tagger",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mint-amazon-tagger"
}
JSON
