Skip to main content

amazon-orders - A Python library (and CLI) for Amazon order history

Version PyPI - Downloads Python Versions Coverage Build Docs GitHub License

amazon-orders is an unofficial library that provides a Python API (and CLI) for Amazon order history, line items, and transactions. Signing in to Amazon is handled by amazon-auth, the authentication package amazon-orders is built on.

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. ==5.3.*, not ==5.3.0) to ensure you always get the latest stable release.

Basic Usage

You'll use AmazonSession to authenticate your Amazon account, then AmazonOrders, AmazonTransactions, AmazonGiftCards, and AmazonPrime to interact with account data. get_orders 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_orders(year=2023)

# Or use time filters for recent orders
orders = amazon_orders.get_orders(time_filter=Constants.LAST_30_DAYS_TIME_FILTER)
orders = amazon_orders.get_orders(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 orders 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 orders --year 2023
amazon-orders orders --last-30-days
amazon-orders orders --last-3-months
amazon-orders search-orders "coffee"

Output Formats

Commands that return Orders, Transactions, and other entities accept --output, which renders them as text (the default), json, yaml, or csv. Progress messages are written to stderr, so redirecting stdout captures only the data.

amazon-orders orders --year 2023 --output json > orders.json
amazon-orders orders --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_orders(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 (pip install amazon-orders[browser], see Browser Automation).

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.

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 config option. 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.

Documentation

For more advanced usage, amazon-orders's official documentation is available at Read the Docs, including handling login challenges (AWS WAF and JavaScript checks, with optional extras) and troubleshooting.

Contributing

If you would like to get involved, be sure to review the Contribution Guide.

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

Metadata

Release files for amazon-orders 5.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amazon-orders 5.3.0
File Size Uploaded Provenance Actions
amazon_orders-5.3.0.tar.gz 80.5 kB With provenance Details for amazon_orders-5.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amazon-orders 5.3.0
File Interpreter ABI Platform Actions
amazon_orders-5.3.0-py3-none-any.whl Python 3 none any Details for amazon_orders-5.3.0-py3-none-any.whl

Total release size: 163.1 kB

Release files / amazon_orders-5.3.0.tar.gz

Download URL amazon_orders-5.3.0.tar.gz
Size 80.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ec13ea3e2c34278d9ea4f6d346dd15c66ee05de70e8f6cfd0f285c4974519235
BLAKE2b-256 checksum
How to use checksums
5e6ebbdb9e6f065a665e47dbf7fa3deb0e20e8019675b84b6c765d6e04a0b53e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / amazon_orders-5.3.0-py3-none-any.whl

Download URL amazon_orders-5.3.0-py3-none-any.whl
Size 82.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d40bdfe920f3413ab28d22a8f795cee69375c2f6cc81f6aff8e9ee36176baa2d
BLAKE2b-256 checksum
How to use checksums
ffc6a71ce4915456c42a1ade53c1aa65f6fcd3af4d049e91217b9f39def6cf60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for amazon-orders 5.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for amazon_orders-5.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

5.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page