https://github.com/alexdlaird/amazon-orders
A Python library (and CLI) for Amazon order history, line items, and transactions
https://github.com/alexdlaird/amazon-orders
amazon beautifulsoup cli order-history python receipts web-scraping
Last synced: 9 days ago
JSON representation
A Python library (and CLI) for Amazon order history, line items, and transactions
- Host: GitHub
- URL: https://github.com/alexdlaird/amazon-orders
- Owner: alexdlaird
- License: mit
- Created: 2024-01-05T16:21:11.000Z (over 2 years ago)
- Default Branch: develop
- Last Pushed: 2026-06-05T18:34:54.000Z (15 days ago)
- Last Synced: 2026-06-05T20:12:34.883Z (15 days ago)
- Topics: amazon, beautifulsoup, cli, order-history, python, receipts, web-scraping
- Language: Python
- Homepage: https://amazon-orders.readthedocs.io
- Size: 3.16 MB
- Stars: 149
- Watchers: 5
- Forks: 41
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.rst
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-cli-apps - amazon-orders - Retrieve Amazon order history. (Utilities / Calendars)
- fucking-awesome-cli-apps - amazon-orders - Retrieve Amazon order history. (Utilities / Calendars)
- awesome-data-hoarding - amazon-orders
README
[](https://pypi.org/project/amazon-orders)
[](https://pypi.org/project/amazon-orders)
[](https://codecov.io/gh/alexdlaird/amazon-orders)
[](https://github.com/alexdlaird/amazon-orders/actions/workflows/build.yml)
[](https://amazon-orders.readthedocs.io)
[](https://github.com/alexdlaird/amazon-orders/blob/main/LICENSE)
`amazon-orders` is an unofficial library that provides a Python API (and CLI) for Amazon order history, line items, and transactions.
Only the English, `.com` version of Amazon is officially supported. Other Amazon domains can be
targeted by passing `domain` to [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession)
(or `--domain` on the CLI), and other English-based sites may work by chance — see
[Known Limitations](https://amazon-orders.readthedocs.io/index.html#known-limitations) for details.
> **Note:** This package works by parsing data from Amazon's consumer-facing website. A periodic build validates
> functionality to ensure its stability, but as Amazon provides no official API to use, older versions of this
> package may break at any time, so it's recommended that you use the latest version.
## Installation
`amazon-orders` is available on [PyPI](https://pypi.org/project/amazon-orders/) and can be installed and/or upgraded using `pip`:
```sh
pip install amazon-orders --upgrade
```
That's it! `amazon-orders` is now available as a package to your Python projects and from the command line.
If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.4.*`, not `==4.4.0`) to
ensure you always get the latest stable release.
## Basic Usage
You'll use [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession) to
authenticate your Amazon account, then [`AmazonOrders`](https://amazon-orders.readthedocs.io/api.html#amazonorders.orders.AmazonOrders)
and [`AmazonTransactions`](https://amazon-orders.readthedocs.io/api.html#amazonorders.transactions.AmazonTransactions)
to interact with account data. [`get_order_history`](https://amazon-orders.readthedocs.io/api.html#amazonorders.orders.AmazonOrders.get_order_history)
and [`get_order`](https://amazon-orders.readthedocs.io/api.html#amazonorders.orders.AmazonOrders.get_order) are good places to start.
```python
from amazonorders.session import AmazonSession
from amazonorders.orders import AmazonOrders
amazon_session = AmazonSession("",
"")
amazon_session.login()
amazon_orders = AmazonOrders(amazon_session)
# Get orders from a specific year
orders = amazon_orders.get_order_history(year=2023)
# Or use time filters for recent orders
orders = amazon_orders.get_order_history(time_filter="last30") # Last 30 days
orders = amazon_orders.get_order_history(time_filter="months-3") # Past 3 months
for order in orders:
print(f"{order.order_number} - {order.grand_total}")
```
If the fields you're looking for aren't populated with the above, set `full_details=True` (or pass `--full-details` to
the `history` CLI command), since by default it is `False` (enabling it slows down querying, since an additional
request for each order is necessary). Have a look at the [Order](https://amazon-orders.readthedocs.io/api.html#amazonorders.entity.order.Order) entity's docs to see what fields are only
populated with full details.
### Command Line Usage
You can also run any command available to the main Python interface from the command line:
```sh
amazon-orders login
amazon-orders history --year 2023
amazon-orders history --last-30-days
amazon-orders history --last-3-months
```
### Automating Authentication
Authentication can be automated by (in order of precedence) storing credentials in environment variables, passing them
to [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession), or storing them
in [`AmazonOrdersConfig`](https://amazon-orders.readthedocs.io/api.html#amazonorders.conf.AmazonOrdersConfig). The
environment variables `amazon-orders` looks for are:
- `AMAZON_USERNAME`
- `AMAZON_PASSWORD`
- `AMAZON_OTP_SECRET_KEY` (see [docs for usage](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession.otp_secret_key))
To enable **WAF auto-solve** via a third-party integration, install with the relevant extra:
```sh
pip install amazon-orders[capsolver]
pip install amazon-orders[anticaptcha]
pip install amazon-orders[2captcha]
```
See [Solving WAF Challenges](https://amazon-orders.readthedocs.io/waf.html) for details.
To enable **browser-based challenge handling** (ACIC and JavaScript bot-detection pages) via
a headless browser, install with the `browser` extra:
```sh
pip install amazon-orders[browser]
playwright install chromium
```
See [Browser Automation](https://amazon-orders.readthedocs.io/browser.html) for details.
For **legacy Captcha auto-solve** on Python <=3.12, install with `captcha` extra:
```sh
pip install amazon-orders[captcha]
```
See [Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
## Documentation
For more advanced usage, `amazon-orders`'s official documentation is available
at [Read the Docs](http://amazon-orders.readthedocs.io).
## Contributing
If you would like to get involved, be sure to review
the [Contribution Guide](https://github.com/alexdlaird/amazon-orders/blob/main/CONTRIBUTING.rst).
Want to contribute financially? If you've found `amazon-orders`
useful, [sponsorship](https://github.com/sponsors/alexdlaird) would
also be greatly appreciated!