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

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 (or --domain on the CLI), and other English-based sites may work by chance – see 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 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 (ex. ==4.2.*, not ==4.2.1) to ensure you always get the latest stable release.

Basic Usage

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

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

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)

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 Captcha auto-solve on Python <=3.12 (via the optional amazoncaptcha dependency), install with the captcha extra:

pip install amazon-orders[captcha]

Without this extra, Captcha challenges fall back to manual entry. amazoncaptcha is not available on Python 3.13+; see Troubleshooting for details.

Known Limitations

• Non-English, non-.com versions of Amazon are unsupported

  • Pass domain to AmazonSession (or set domain in AmazonOrdersConfig, or pass --domain on the CLI) to point at another Amazon site. URLs and the URL-shaped headers (Origin, Host, Referer) are rewritten from the domain, and Accept-Language is adjusted for a small set of English-locale TLDs, so other English-based versions of Amazon (ex. amazon.ca) may work by chance. Other values such as the OpenID assoc_handle are not adjusted — subclass Constants and set constants_class to override them if a particular site requires it. The AMAZON_BASE_URL environment variable continues to work as a fallback.

  • We do not run nightly regressions against non-.com versions of the site, and as such do not say they are officially supported. If you fork the repo, point the integration.yml workflow at a different domain with your own credentials, please contact us and we will start mentioning support for that version of the site.

  • See issue #15 for more details.

• 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.

• API Documentation
  • Main Interface
  • Session Management
  • Configuration
  • Entities
  • Exceptions
  • Utility Functions
• Solving WAF Challenges
  • CapSolver
  • Anti-Captcha
  • 2Captcha
  • Writing Your Own
• Troubleshooting
  • Enable Debug Mode
  • Captcha Blocking Login
  • Slow Parsing / Malformed Data
  • Concurrency Workers Exhausted
  • URL Connection Pool Full
  • Broken After Previously Working
  • Found an Unknown Page in Auth Flow
  • Found a Missing / Broken Field on an Entity

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.

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!