alexdlaird

amazon-orders

<p align="center"><img alt="amazon-orders - A Python library (and CLI) for Amazon order history" src="https://amazon-orders.readthedocs.io/_images/logo.png" /></p> [](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.3.*`, not `==4.2.1`) 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_EMAIL>", "<AMAZON_PASSWORD>") 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!