Metadata-Version: 2.4
Name: amazon-orders
Version: 4.4.0
Summary: A Python library (and CLI) for Amazon order history
Author-email: Alex Laird <contact@alexlaird.com>
Maintainer-email: Alex Laird <contact@alexlaird.com>
License-Expression: MIT
Project-URL: Changelog, https://github.com/alexdlaird/amazon-orders/blob/main/CHANGELOG.md
Project-URL: Documentation, https://amazon-orders.readthedocs.io
Project-URL: Sponsor, https://github.com/sponsors/alexdlaird
Project-URL: Source Code, https://github.com/alexdlaird/amazon-orders
Keywords: amazon,orders,order-history,scraper,web-scraping,receipts,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=7.1
Requires-Dist: requests>=2.23
Requires-Dist: Pillow>=9.0.1
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: pyotp>=2.9
Provides-Extra: browser
Requires-Dist: playwright>=1.47.0; extra == "browser"
Provides-Extra: capsolver
Requires-Dist: capsolver; extra == "capsolver"
Provides-Extra: anticaptcha
Requires-Dist: anticaptchaofficial; extra == "anticaptcha"
Provides-Extra: 2captcha
Requires-Dist: 2captcha-python; extra == "2captcha"
Provides-Extra: lxml
Requires-Dist: lxml; extra == "lxml"
Provides-Extra: captcha
Requires-Dist: amazoncaptcha>=0.4; extra == "captcha"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage[toml]; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: flake8-pyproject; extra == "dev"
Requires-Dist: pep8-naming; extra == "dev"
Requires-Dist: responses; extra == "dev"
Requires-Dist: lxml; extra == "dev"
Provides-Extra: integration
Requires-Dist: pytest-rerunfailures; extra == "integration"
Requires-Dist: parameterized; extra == "integration"
Provides-Extra: docs
Requires-Dist: Sphinx; extra == "docs"
Requires-Dist: sphinx-notfound-page; extra == "docs"
Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
Requires-Dist: mypy; extra == "docs"
Requires-Dist: types-requests; extra == "docs"
Requires-Dist: types-beautifulsoup4; extra == "docs"
Requires-Dist: types-Pillow; extra == "docs"
Requires-Dist: types-PyYAML; extra == "docs"
Requires-Dist: types-python-dateutil; extra == "docs"
Requires-Dist: sphinx-sitemap; extra == "docs"
Requires-Dist: sphinxext-opengraph; extra == "docs"
Dynamic: license-file

<p align="center"><img alt="amazon-orders - A Python library (and CLI) for Amazon order history" src="https://amazon-orders.readthedocs.io/_images/logo.png" /></p>

[![Version](https://img.shields.io/pypi/v/amazon-orders)](https://pypi.org/project/amazon-orders)
[![Python Versions](https://img.shields.io/pypi/pyversions/amazon-orders.svg)](https://pypi.org/project/amazon-orders)
[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/amazon-orders)](https://codecov.io/gh/alexdlaird/amazon-orders)
[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/amazon-orders/build.yml)](https://github.com/alexdlaird/amazon-orders/actions/workflows/build.yml)
[![Docs](https://img.shields.io/readthedocs/amazon-orders)](https://amazon-orders.readthedocs.io)
[![GitHub License](https://img.shields.io/github/license/alexdlaird/amazon-orders)](https://github.com/alexdlaird/amazon-orders/blob/main/LICENSE)

`amazon-orders` is an unofficial library that provides a Python API (and CLI) for Amazon order history, line items, and transactions.

Only the English, `.com` version of Amazon is officially supported. Other Amazon domains can be
targeted by passing `domain` to [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession)
(or `--domain` on the CLI), and other English-based sites may work by chance — see
[Known Limitations](https://amazon-orders.readthedocs.io/index.html#known-limitations) for details.

> **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](https://pypi.org/project/amazon-orders/) and can be installed and/or upgraded using `pip`:

```sh
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](https://semver.org/) (ex. `==4.4.*`, not `==4.2.1`) to
ensure you always get the latest stable release.

## Basic Usage

You'll use [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession) to
authenticate your Amazon account, then [`AmazonOrders`](https://amazon-orders.readthedocs.io/api.html#amazonorders.orders.AmazonOrders)
and [`AmazonTransactions`](https://amazon-orders.readthedocs.io/api.html#amazonorders.transactions.AmazonTransactions)
to interact with account data. [`get_order_history`](https://amazon-orders.readthedocs.io/api.html#amazonorders.orders.AmazonOrders.get_order_history)
and [`get_order`](https://amazon-orders.readthedocs.io/api.html#amazonorders.orders.AmazonOrders.get_order) are good places to start.

```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)

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

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](https://amazon-orders.readthedocs.io/api.html#amazonorders.entity.order.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:

```sh
amazon-orders login
amazon-orders history --year 2023
amazon-orders history --last-30-days
amazon-orders history --last-3-months
```

### Automating Authentication

Authentication can be automated by (in order of precedence) storing credentials in environment variables, passing them
to [`AmazonSession`](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession), or storing them
in [`AmazonOrdersConfig`](https://amazon-orders.readthedocs.io/api.html#amazonorders.conf.AmazonOrdersConfig). The
environment variables `amazon-orders` looks for are:

- `AMAZON_USERNAME`
- `AMAZON_PASSWORD`
- `AMAZON_OTP_SECRET_KEY` (see [docs for usage](https://amazon-orders.readthedocs.io/api.html#amazonorders.session.AmazonSession.otp_secret_key))

To enable **WAF auto-solve** via a third-party integration, install with the relevant extra:

```sh
pip install amazon-orders[capsolver]
pip install amazon-orders[anticaptcha]
pip install amazon-orders[2captcha]
```

See [Solving WAF Challenges](https://amazon-orders.readthedocs.io/waf.html) for details.

To enable **browser-based challenge handling** (ACIC and JavaScript bot-detection pages) via
a headless browser, install with the `browser` extra:

```sh
pip install amazon-orders[browser]
playwright install chromium
```

See [Browser Automation](https://amazon-orders.readthedocs.io/browser.html) for details.

For **legacy Captcha auto-solve** on Python <=3.12, install with `captcha` extra:

```sh
pip install amazon-orders[captcha]
```

See [Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.

## Documentation

For more advanced usage, `amazon-orders`'s official documentation is available
at [Read the Docs](http://amazon-orders.readthedocs.io).

## Contributing

If you would like to get involved, be sure to review
the [Contribution Guide](https://github.com/alexdlaird/amazon-orders/blob/main/CONTRIBUTING.rst).

Want to contribute financially? If you've found `amazon-orders`
useful, [sponsorship](https://github.com/sponsors/alexdlaird) would
also be greatly appreciated!
