Amazon Orders CLI

Walk your Amazon order history offline — every order, item, shipment, and dollar in a local SQLite store no other tool gives you.

Sync once and ask cross-cutting questions forever. Where is my stuff right now, what did I spend last quarter, which deliveries are slipping, when did I order that thing — answered in milliseconds without re-hitting the live site or burning agent context on full HTML pages.

Learn more at Amazon Orders.

Created by @bwishan (Brian Wishan). Contributors: @tmchow (Trevin Chow).

Authentication

Amazon publishes no buyer API. The CLI imports cookies from your logged-in Chrome / Firefox / Safari / Brave session via auth login --chrome. Those cookies persist locally, refresh automatically, and authenticate every subsequent fetch — no API key, no OAuth, no resident browser at runtime.

For non-US Amazon marketplaces, pass the marketplace domain during login. The CLI will read cookies for that domain and persist the matching base URL for later commands:

amazon-orders-pp-cli auth login --chrome --domain amazon.in

You can also set AMAZON_ORDERS_BASE_URL=https://www.amazon.in before running auth login --chrome.

Headless agents (1Password / Vault / Bitwarden)

For CI, dev containers, and remote hosts where auth login --chrome is not viable, capture the session once on a logged-in machine and inject it on every other host via your secrets manager. The cookie value never enters an LLM's context window because the bytes flow op → stdin → CLI without a shell variable in the middle.

# Stash once (logged-in machine):
amazon-orders-pp-cli auth export | op document create - --title amazon-orders-session --vault Agent

# Inject on any other machine:
op read "op://Agent/amazon-orders-session/file" | amazon-orders-pp-cli auth import --stdin

The exported JSON shape is amazon-orders-session/v1. auth import also accepts --input <file>, the AMAZON_COOKIES env var, or a raw "k=v; k=v" cookie string with --raw-cookies. See SKILL.md ("Headless agent setup with 1Password") for the refresh recipe and substitutes for vault kv get, aws secretsmanager, pass, and bw.

Quick Start

# Import cookies from your logged-in browser session — required for any authenticated fetch.
amazon-orders-pp-cli auth login --chrome

# Non-US marketplace example.
amazon-orders-pp-cli auth login --chrome --domain amazon.in

# Walk the last 3 months of orders into the local store, including per-order item detail.
amazon-orders-pp-cli sync --since 90d --concurrency 1

# See every in-flight package with current status and ETA.
amazon-orders-pp-cli where-is-my-stuff --json

# Roll up your 2026 Amazon spending by month.
amazon-orders-pp-cli spend --by month --year 2026 --json

# Find every order containing 'usb-c cable' — FTS5-backed, instant, offline.
amazon-orders-pp-cli find 'usb-c cable' --json

Unique Features

These capabilities aren't available in any other tool for this API.

Local state that compounds

• where-is-my-stuff — All in-flight Amazon shipments with their current status and ETA in one view.

  When an agent needs to answer 'is my package coming today' across many orders, this is the one-shot view.

  amazon-orders-pp-cli where-is-my-stuff --json --select orderId,status,etaDate,carrier
  

• delivery-slips — Orders whose actual delivery date slipped more than N days from the original estimate.

  Surfaces unreliable carriers and sellers without manually scrolling through every order.

  amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01 --json
  

• spend — Spending broken down by month, year, category, seller, or payment method.

  Gives agents a one-shot answer for budgeting, expense reporting, and trend analysis.

  amazon-orders-pp-cli spend --by month --year 2025 --json
  

• top-items — Most-ordered items by frequency or by total spend, ASIN-grouped across all history.

  Helps an agent reason about what the user actually consumes vs one-off purchases.

  amazon-orders-pp-cli top-items --by total-spend --limit 20 --json
  

• subscribe-and-save — Recurring purchases inferred from order history (same ASIN ordered on a regular cadence).

  Surfaces candidates for actual S&S enrollment and detects de-facto subscriptions the user may not realize they have.

  amazon-orders-pp-cli subscribe-and-save --min-occurrences 3 --json
  

• arriving-soon — Shipments arriving in the next N days, sorted by ETA.

  Lets an agent plan around incoming deliveries (e.g. 'is my router arriving before the meeting on Friday?').

  amazon-orders-pp-cli arriving-soon --days 7 --json
  

• late — Active shipments past their original estimated delivery date.

  Surfaces carrier delays the moment they happen, no manual review.

  amazon-orders-pp-cli late --json
  

Agent-native plumbing

• find — FTS5 search across orders, items, sellers, and tracking notes.

  Direct answer to 'when did I order that thing' without scrolling through years of order history.

  amazon-orders-pp-cli find 'usb-c cable' --json --select orderId,placedDate,total
  

Usage

Run amazon-orders-pp-cli --help for the full command reference and flag list.

Commands

gift_cards

Gift card balance and activity history.

• amazon-orders-pp-cli gift_cards balance - Current gift card balance plus the activity log: amounts, kinds (added/applied/refund), dates, linked order IDs.

orders

Your buyer-side order history listings and per-order detail pages.

• amazon-orders-pp-cli orders get - Full detail for a single order: items, ASINs, prices, shipments, payment method, ship-to address, totals.
• amazon-orders-pp-cli orders invoice - Printable invoice for an order (HTML), useful for VAT/expense reconciliation.
• amazon-orders-pp-cli orders list - Fetch one page of your order history. Use timeFilter (year-2026, last30days, months-3) and startIndex to paginate.

shipments

Per-package tracking details.

• amazon-orders-pp-cli shipments track - Tracking detail for a single shipment: carrier, tracking number, status, ETA, delivery confirmation.

transactions

Charges and refunds across all orders, recurring services, and Prime.

• amazon-orders-pp-cli transactions list - First page of your transactions list, grouped by date. Each row has payment method, last-4, signed amount, and (when applicable) the linked order ID.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
amazon-orders-pp-cli orders list

# JSON for scripting and agents
amazon-orders-pp-cli orders list --json

# Filter to specific fields
amazon-orders-pp-cli orders list --json --select id,name,status

# Dry run — show the request without sending
amazon-orders-pp-cli orders list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
amazon-orders-pp-cli orders list --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Freshness

This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.

Set AMAZON_ORDERS_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.

Covered command paths:

• amazon-orders-pp-cli orders
• amazon-orders-pp-cli orders get
• amazon-orders-pp-cli orders invoice
• amazon-orders-pp-cli orders list
• amazon-orders-pp-cli transactions

JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.

Health Check

amazon-orders-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/amazon-orders-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
AMAZON_COOKIES	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run amazon-orders-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $AMAZON_COOKIES Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• auth status reports unauthenticated after auth login --chrome — Make sure you're logged in to the same Amazon marketplace in Chrome, then re-run with the matching domain, e.g. auth login --chrome --domain amazon.in.
• sync fails with RateLimitError after ~10 orders — Pass --rate 0.5 to slow the per-order detail fetch, or omit --full-details to fetch only the listing pages.
• Order detail returns 401 even when logged in — Amazon rotated your session-id; re-run auth login --chrome to refresh cookies.
• track <id> returns empty when the order has multiple shipments — Pass --shipment-id <SID> (visible in orders get <id> --json) to disambiguate.
• Foreign-locale orders parse with garbled dates — marketplace auth is supported, but some localized order-history date formats may still need parser fixes.

Discovery Signals

This CLI was generated with browser-captured traffic analysis.

• Target observed: https://www.amazon.com/gp/your-account/order-history
• Capture coverage: 6 API entries from 6 total network entries
• Reachability: standard_http (95% confidence)
• Protocols: html_cookie (85% confidence)

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• amazon-orders — Python
• amazon-order-history-csv-download-mcp — TypeScript
• azad — TypeScript
• Amazon-Order-History — Python
• amazon_order_history_scraper — Python

Generated by CLI Printing Press