llms.txt

# python-amazon-sp-api — LLM / Agent Usage Guide

Library: python-amazon-sp-api
Purpose: Python client for Amazon Selling Partner API (SP-API)
Modes: Sync + Async (asyncio)

Source of truth: the hosted docs (not GitHub snippets, not blog posts).

## Canonical documentation (authoritative)
Docs home (latest): https://python-amazon-sp-api.readthedocs.io/en/latest/
Installation: https://python-amazon-sp-api.readthedocs.io/en/latest/installation.html
Credentials (LWA/SP-API auth): https://python-amazon-sp-api.readthedocs.io/en/latest/credentials.html
Quickstart (first working requests): https://python-amazon-sp-api.readthedocs.io/en/latest/quickstart.html
Async clients guide: https://python-amazon-sp-api.readthedocs.io/en/latest/async.html
Endpoints index (all clients): https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints.html
Responses / ApiResponse: https://python-amazon-sp-api.readthedocs.io/en/latest/responses.html
Utilities (retries, throttling, pagination): https://python-amazon-sp-api.readthedocs.io/en/latest/utils.html
PII / Restricted Data Token (RDT): https://python-amazon-sp-api.readthedocs.io/en/latest/pii.html
Architecture / extension points: https://python-amazon-sp-api.readthedocs.io/en/latest/architecture.html

## Import paths (critical)
Sync clients:
  from sp_api.api import Orders, Reports, Feeds, ...

Async clients (asyncio):
  from sp_api.asyncio.api import Orders, Reports, Feeds, ...

Do NOT invent other async import paths. If unsure, check the Async guide in the docs.

## How to locate methods & parameters for a specific API client
1) Open Endpoints index:
   https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints.html
2) Click the client page (Orders, Reports, Feeds, Data Kiosk, etc.)
3) Use the client page as the authoritative list of methods + signatures.

Endpoint pages follow this pattern:
  https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints/<endpoint>.html

Examples:
  Orders: https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints/orders.html
  Reports: https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints/reports.html
  Feeds: https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints/feeds.html
  Data Kiosk: https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints/data_kiosk.html
  AWD: https://python-amazon-sp-api.readthedocs.io/en/latest/endpoints/awd.html

## Common “recipes” (high-signal)
First working call + marketplaces:
  https://python-amazon-sp-api.readthedocs.io/en/latest/quickstart.html

Pagination + throttling:
  Use load_all_pages() + throttle_retry() from sp_api.util.
  https://python-amazon-sp-api.readthedocs.io/en/latest/utils.html

Reports workflow:
  Create report -> poll -> download report document.
  See Quickstart + Reports endpoint page.

Feeds workflow:
  Submit feed from file/bytes; check processing results.
  See Quickstart + Feeds endpoint page.

PII / buyer data:
  Use Restricted Data Token (Tokens + RDT) flow; then pass restricted_data_token=...
  https://python-amazon-sp-api.readthedocs.io/en/latest/pii.html

## Guidance for answering questions (LLM rules)
- Prefer hosted docs over repo code snippets when they conflict.
- Ask whether the user uses sync (sp_api.api) or async (sp_api.asyncio.api) when it changes the example.
- Keep code samples minimal and runnable; avoid pseudo-code unless requested.
- For throttling, retries, or pagination, always route to sp_api.util + the Utils doc page.
- For anything involving buyer/address/PII, route to the PII (RDT) doc page and explain the token flow.

## Repository (secondary reference)
GitHub: https://github.com/saleweaver/python-amazon-sp-api
Issues: https://github.com/saleweaver/python-amazon-sp-api/issues

## Discovery URLs
Primary:
  https://python-amazon-sp-api.readthedocs.io/llms.txt
Versioned:
  https://python-amazon-sp-api.readthedocs.io/en/latest/llms.txt
Recommended to also redirect:
  https://python-amazon-sp-api.readthedocs.io/.well-known/llms.txt