Amazon Orders

Download and query your Amazon order history via an unofficial Python API and CLI.

Security Scan

The skill's stated purpose (scraping your Amazon order history) is coherent with the tools and credentials it asks for, but there are inconsistencies and sensitive requirements (an OTP secret declared as required by the registry though the documentation says it's optional) that warrant caution before installing and supplying credentials.

Purpose & Capability

Name/description match what the SKILL.md actually instructs (install and run the unofficial amazon-orders Python package). Requested binaries (python3, pip3) and environment variables for Amazon credentials are consistent with an automated scraper that logs into an account. However, the registry metadata lists AMAZON_OTP_SECRET_KEY as a required env var while the SKILL.md explicitly says that OTP/TOTP is optional for accounts that have MFA — this mismatch is disproportionate and should be clarified.

Instruction Scope

SKILL.md stays on-purpose: it tells the agent to pip install the package, to supply credentials via env vars or parameters, and to run the library or CLI to fetch order history. It does not instruct the agent to read unrelated files, harvest additional system secrets, or send data to endpoints outside the documented project. The doc does recommend storing credentials in env vars and using an OTP secret for automation, which is within scope for automated login but has security implications.

Install Mechanism

There is no formal install spec in the registry; the SKILL.md tells users to run `python3 -m pip install --upgrade amazon-orders`. Installing from PyPI is a common pattern but carries normal supply-chain risk (pip package code will be downloaded and executed). The homepage points to a GitHub repo, which is expected; no remote download from unknown hosts is required by the SKILL.md itself.

Credentials

The skill requires AMAZON_USERNAME and AMAZON_PASSWORD (expected) and the registry also lists AMAZON_OTP_SECRET_KEY as required. The SKILL.md describes the OTP secret as optional for accounts with MFA. Declaring the OTP secret mandatory is disproportionate and sensitive: an OTP/TOTP secret in environment variables allows unattended login and effectively bypasses MFA protections. The number and sensitivity of required env vars are otherwise appropriate for a login-based scraper, but the mandatory OTP secret is a red flag unless you explicitly need unattended runs.

Persistence & Privilege

always:false (no forced global inclusion) and model-invocation is enabled (default). That means the agent could invoke the skill autonomously if permitted. Combining autonomous invocation with stored Amazon credentials (especially an OTP secret) increases risk because the agent could sign in and act on the account without interactive confirmation. This is not by itself a fatal issue, but be aware of the blast radius before enabling autonomous runs.

What to consider before installing

This skill appears to be what it claims (a wrapper around the unofficial amazon-orders Python package), but you should be cautious about supplying credentials. Key points to consider before installing or enabling it: - The registry metadata marks AMAZON_OTP_SECRET_KEY as required, but the SKILL.md says the OTP/TOTP secret is optional for accounts with MFA — ask the publisher or registry maintainer to clarify whether the OTP secret is mandatory. - Never store your Amazon password or OTP secret in plaintext where you don't control access. Prefer interactive login or a secure secrets manager (Vault, 1Password, GitHub Actions secrets) and avoid placing long-lived OTP secrets in environment variables unless you understand the risk. - Installing via `pip` will fetch the package from PyPI and run its code on your system. Review the package source (the linked GitHub repo) and pin a version to avoid unexpected upgrades or supply-chain issues. - If you enable autonomous agent invocation, be aware the agent could log in and fetch orders without further prompts — that increases the impact if credentials are compromised. - If you do not trust the package author or cannot verify the repository, do not provide credentials; consider running the tool in an isolated environment (ephemeral VM or container) and limit network/credential exposure. If you want a safer setup: confirm whether OTP is actually required, use short-lived or restricted credentials where possible, review the upstream project code, and prefer interactive login flows or delegated authentication over storing TOTP secrets in env vars.

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="[e-mail]"
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.).