amazon-orders Skill

Interact with your Amazon.com order history using the unofficial amazon-orders Python package and CLI.

Note: amazon-orders works by scraping/parsing Amazon's consumer website, so it can break if Amazon changes their pages. Only the English Amazon .com site is officially supported.

Setup

Install / upgrade

python3 -m pip install --upgrade amazon-orders

(Install details and version pinning guidance are in the project README.)

Authentication options

amazon-orders can get credentials from (highest precedence first): environment variables, parameters passed to AmazonSession, or a local config.

Environment variables:

export AMAZON_USERNAME="you@example.com"
export AMAZON_PASSWORD="your-password"
# Optional: for accounts with OTP/TOTP enabled
export AMAZON_OTP_SECRET_KEY="BASE32_TOTP_SECRET"

(OTP secret key usage is documented by the project.)

Usage

You can use amazon-orders either as a Python library or from the command line.

Python: basic usage

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)

# Orders from a specific year
orders = amazon_orders.get_order_history(year=2023)

# Or use a time filter 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}")

Full details (slower, more fields)

Some order fields only populate when you request full details; enable it when you need richer order data:

• Python: full_details=True
• CLI: --full-details on history

CLI: common commands

# Authenticate (interactive / uses env vars if set)
amazon-orders login

# Order history
amazon-orders history --year 2023
amazon-orders history --last-30-days
amazon-orders history --last-3-months

Tips

• If your account has MFA enabled, prefer setting AMAZON_OTP_SECRET_KEY for automated runs.
• When automating, keep credentials out of shell history: use environment variables and a secret manager (1Password, Vault, GitHub Actions secrets, etc.).

Examples

Export yearly history to JSON

amazon-orders history --year 2023 --full-details > orders_2023.json

Quick totals check (requires jq)

amazon-orders history --last-30-days --full-details   | jq -r '.[] | [.order_number, .grand_total] | @tsv'

Notes

• This is an unofficial scraper-based tool (no official Amazon API).
• Official docs are hosted on Read the Docs for advanced usage and APIs (Orders, Transactions, etc.).