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_USERNAMEAMAZON_PASSWORDAMAZON_OTP_SECRET_KEY(seeotp_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, oramazon.de): set thedomainconfig 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 letsamazon-ordersread 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!
1 maintainer
Metadata
1 maintainer
Release files for amazon-orders 4.9.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| amazon_orders-4.9.3.tar.gz | 95.1 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| amazon_orders-4.9.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 193.4 kB
Release files / amazon_orders-4.9.3.tar.gz
| Download URL | amazon_orders-4.9.3.tar.gz |
|---|---|
| Size | 95.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
78f7a8a02d41dd2be5f08fc3cc762bf75d1b8ce62b010634d8298c53d756f5c7
|
|
BLAKE2b-256 checksum How to use checksums |
ef74c836ee4608a4ff16b203aeddb5dca08ebfcda36c7f0754112fc821a03576
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / amazon_orders-4.9.3-py3-none-any.whl
| Download URL | amazon_orders-4.9.3-py3-none-any.whl |
|---|---|
| Size | 98.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a4615e6f61b06066e14260905b3f2250e6c4968a12274fba506b7e2dc34939fa
|
|
BLAKE2b-256 checksum How to use checksums |
71f68adac9482a914b8a3823ff17715253d3dad39eed9e898ecf3148436c0661
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for amazon-orders 4.9.3
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.
