Amazon Orders - A Python library (and CLI) for Amazon order history, line items, and transactions


https://img.shields.io/pypi/v/amazon-orders https://img.shields.io/pypi/pyversions/amazon-orders.svg https://img.shields.io/codecov/c/github/alexdlaird/amazon-orders https://img.shields.io/github/actions/workflow/status/alexdlaird/amazon-orders/build.yml https://img.shields.io/readthedocs/amazon-orders https://img.shields.io/github/license/alexdlaird/amazon-orders

amazon-orders is an unofficial library that provides a Python API (and CLI) for Amazon order history, line items, and transactions.

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 and can be installed and/or upgraded using pip:

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 (e.g. ==4.9.*, not ==4.9.0) to ensure you always get the latest stable release.

Basic Usage

You’ll use AmazonSession to authenticate your Amazon account, then AmazonOrders, AmazonTransactions, and AmazonGiftCards to interact with account data. get_order_history and get_order are good places to start.

from amazonorders.constants import Constants
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=Constants.LAST_30_DAYS_TIME_FILTER)
orders = amazon_orders.get_order_history(time_filter=Constants.LAST_3_MONTHS_TIME_FILTER)

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 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:

amazon-orders login
amazon-orders history --year 2023
amazon-orders history --last-30-days
amazon-orders history --last-3-months

Output Formats

The history, order, transactions, order-transactions, and gift-card-activity commands accept --output, which renders Orders, Transactions, and Gift Card activity as text (the default), json, yaml, or csv. Progress messages are written to stderr, so redirecting stdout captures only the data.

amazon-orders history --year 2023 --output json > orders.json
amazon-orders history --last-30-days --output csv > orders.csv

To serialize from Python instead, every entity has to_dict, which converts it and its nested entities to a dict of primitives.

import json

from amazonorders.orders import AmazonOrders

amazon_orders = AmazonOrders(amazon_session)
orders = amazon_orders.get_order_history(year=2023)

# [{"order_number": "112-9685975-5907428", "grand_total": 35.98, ...}]
print(json.dumps([order.to_dict() for order in orders], indent=2))

See OutputFormatter for each format’s contract, and to override how entities are rendered.

Secure Sign-In

The most secure way to use amazon-orders is to sign in on Amazon’s own page, in a browser window, so amazon-orders never needs to store your credentials:

amazon-orders login --browser

The session is persisted, so neither the CLI nor the Python API needs credentials:

from amazonorders.session import AmazonSession

amazon_session = AmazonSession()
amazon_session.login()

This requires a display and the browser extra (see Browser Automation to install it).

Automating Authentication

Authentication can be automated by (in order of precedence) storing credentials in environment variables, passing them to AmazonSession, or storing them in AmazonOrdersConfig. The environment variables amazon-orders looks for are:

  • AMAZON_USERNAME

  • AMAZON_PASSWORD

  • AMAZON_OTP_SECRET_KEY (see otp_secret_key)

Any other config value can be set the same way, as AMAZON_<KEY> (see AmazonOrdersConfig).

A configured username also applies to amazon-orders login --browser: it’s filled in and submitted for you, so the browser opens on Amazon’s password or passkey step. The browser never fills in your password.

Handling Challenges

To enable WAF auto-solve via a third-party integration, install with the relevant extra:

pip install amazon-orders[capsolver]
pip install amazon-orders[anticaptcha]
pip install amazon-orders[2captcha]

See Solving WAF Challenges for details.

To enable browser-based challenge handling (ACIC and JavaScript bot-detection pages) via a headless browser, install with the browser extra:

pip install amazon-orders[browser]

See Browser Automation for details.

For legacy Captcha auto-solve on Python <=3.12, install with captcha extra:

pip install amazon-orders[captcha]

See Login Challenges for details.

Languages and Regions

amazon-orders reads Amazon’s pages in English. The .com site is validated nightly.

  • Any other site that offers English (e.g. amazon.co.uk, or amazon.de): set the domain in the config. These are supported on a best-effort basis. See Supported Sites.

  • Any site, in another language: install a language package and set language_package. A language package lets amazon-orders read the site’s pages; its own CLI and messages stay in English. See Language Packages.

AI Assistants

An AI assistant has two ways to use amazon-orders. One that runs commands uses the CLI or the library directly, just as shown above. Any MCP client gets the same as tools through amazon-orders-mcp, a server built on amazon-orders — see its README for setup.

The server signs you in with a browser, so it needs a display. Without one, use the CLI or library with Automating Authentication.

Known Limitations

  • Amazon Business accounts are not supported

  • Device not remembered for OTP

    • Amazon will sometimes re-prompt for OTP even when a device has been remembered.

    • The recommended workaround for this is persisting the otp_secret_key in the config or the environment so that re-prompts are auto-solved.

    • See issue #55 for more details.

Dive Deeper

For more advanced usage, dive deeper in to the rest of the documentation.

Contributing

If you find issues, report them on GitHub.

If you would like to contribute to the code, the process is pretty simple:

  1. Familiarise yourself with this package and its dependencies.

  2. Fork the repository on GitHub and start implementing changes.

  3. Write a test that plainly validates the changes made.

  4. Build and test locally with make local, make test, and make test-integration.

  5. Ensure no linting errors were introduced by running make check.

  6. Submit a pull requests to get the changes merged.

Languages other than English plug in through separately published language packages, so pull requests that add a language here won’t be accepted. See Language Packages for how to build one and get it listed in the docs.

Also be sure to review the Code of Conduct before submitting issues or pull requests.

Want to contribute financially? If you’ve found amazon-orders useful, sponsorship would also be greatly appreciated!