amazon-orders

---
name: amazon-orders
description: Download and query your Amazon order history via an unofficial Python API and CLI.
homepage: https://github.com/alexdlaird/amazon-orders
metadata: {"clawdbot":{"emoji":"📦","requires":{"bins":["python3","pip3"],"env":["AMAZON_USERNAME", "AMAZON_PASSWORD", "AMAZON_OTP_SECRET_KEY"]}}}
---

# 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
```bash
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:
```bash
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

```python
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}")
```