Amazon Seller Central — SP-API#

Run the bundled scripts/amazon_api.py for every Amazon SP-API operation. The script handles the full LWA refresh + AWS SigV4 signing chain internally so the agent only ever deals with structured JSON.

bash

python3 "{baseDir}/scripts/amazon_api.py" <command> [options]

Background: Amazon's Selling Partner API (SP-API) is the replacement for MWS. Auth needs two layers — an LWA refresh token for x-amz-access-token, and IAM credentials for SigV4 request signing. Both are required for every call. Tokens auto-refresh; the agent does not.

First run — install the one Python dependency#

The script uses httpx. If a command fails with ModuleNotFoundError: No module named 'httpx', install it once:

bash

python3 -c "import httpx" || python3 -m pip install httpx

Setup#

Set five required env vars. The cleanest place is your shell rc or your secrets manager (1Password CLI, direnv, systemd EnvFile, etc.). Never paste secrets into chat.

bash

export AMAZON_SP_API_REFRESH_TOKEN="Atzr|…"          # LWA refresh token
export AMAZON_SP_API_CLIENT_ID="amzn1.application-oa2-client.…"
export AMAZON_SP_API_CLIENT_SECRET="…"
export AMAZON_SP_API_AWS_ACCESS_KEY_ID="AKIA…"       # IAM user with SP-API role assumed
export AMAZON_SP_API_AWS_SECRET_ACCESS_KEY="…"

Two optional knobs (sensible defaults — UK marketplace, EU region):

bash

export AMAZON_SP_API_MARKETPLACE_ID="A1F83G8C2ARO7P"  # default: UK
export AWS_REGION="eu-west-1"                          # default: EU endpoint

Region → endpoint mapping the script uses:

AWS_REGIONSP-API endpointRegion labelus-east-1``https://sellingpartnerapi-na.amazon.comNAeu-west-1``https://sellingpartnerapi-eu.amazon.comEU (default)us-west-2``https://sellingpartnerapi-fe.amazon.comFar East

Marketplace ids: https://developer-docs.amazon.com/sp-api/docs/marketplace-ids.

Workflow rules#

1. Start with --summary on every list command. SP-API responses are big and lossy to read in full — only drop --summary after you've narrowed to specific ids.
2. Filter at the API. Every list command exposes the same filters as Seller Central ( --status, --since, --type, --skus). Push them down; don't paginate everything.
3. Reports are async. reports/ create-report/ get-report/ get-report-document are the four-step ritual. For restock specifically, use the restock-report shortcut — it does create → poll-every-10s → download in one call.
4. Token caching is in-process only. Each script invocation refreshes LWA once and caches for ~1 hour, but nothing is persisted to disk — there are no secrets on the filesystem after the process exits.

Commands#

Orders#

bash

python3 "{baseDir}/scripts/amazon_api.py" orders --summary
python3 "{baseDir}/scripts/amazon_api.py" orders --status Unshipped --summary
python3 "{baseDir}/scripts/amazon_api.py" orders --since 2026-01-01 --summary
python3 "{baseDir}/scripts/amazon_api.py" orders --status Shipped --since 2026-01-01 --limit 50

python3 "{baseDir}/scripts/amazon_api.py" order <AmazonOrderId>
python3 "{baseDir}/scripts/amazon_api.py" order-items <AmazonOrderId> --summary

Status values: Unshipped, PartiallyShipped, Shipped, Canceled, Pending, etc.

Catalog#

bash

python3 "{baseDir}/scripts/amazon_api.py" catalog-item <ASIN>

FBA Inventory#

bash

python3 "{baseDir}/scripts/amazon_api.py" inventory --summary
python3 "{baseDir}/scripts/amazon_api.py" inventory --skus "SKU1,SKU2" --summary

Reports#

bash

# List existing report runs
python3 "{baseDir}/scripts/amazon_api.py" reports --summary
python3 "{baseDir}/scripts/amazon_api.py" reports --type GET_FLAT_FILE_OPEN_LISTINGS_DATA --summary

# Kick off a new report
python3 "{baseDir}/scripts/amazon_api.py" create-report --type GET_FLAT_FILE_OPEN_LISTINGS_DATA
python3 "{baseDir}/scripts/amazon_api.py" create-report \
    --type GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL --start 2026-01-01 --end 2026-01-31

# Poll until it's DONE
python3 "{baseDir}/scripts/amazon_api.py" get-report <reportId>

# Download + parse the report document (TSV → JSON)
python3 "{baseDir}/scripts/amazon_api.py" get-report-document <reportDocumentId>
python3 "{baseDir}/scripts/amazon_api.py" get-report-document <reportDocumentId> --output report.tsv

Restock Inventory Report (single-shot)#

bash

# Creates report, polls until done, downloads — all in one step
python3 "{baseDir}/scripts/amazon_api.py" restock-report
python3 "{baseDir}/scripts/amazon_api.py" restock-report --output restock.tsv

Output fields: Product Name, SKU, ASIN, FNSKU, sales over last 30 days, units sold, available, inbound, total units, days of supply, recommended replenishment qty, recommended ship date, alert status. Use this rather than re-implementing the create/poll/download loop.

Finances#

bash

python3 "{baseDir}/scripts/amazon_api.py" finances --since 2026-01-01
python3 "{baseDir}/scripts/amazon_api.py" finances --order-id <AmazonOrderId>
python3 "{baseDir}/scripts/amazon_api.py" finances --since 2026-01-01 --limit 50

Common report types#

Report typeWhat it isGET_RESTOCK_INVENTORY_RECOMMENDATIONS_REPORTRestock recommendations (use restock-report shortcut)GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATAActive FBA inventory detailsGET_FBA_MYI_ALL_INVENTORY_DATAAll FBA inventory (incl. archived)GET_AFN_INVENTORY_DATAFBA inventory quantitiesGET_FBA_INVENTORY_PLANNING_DATAInventory planning (aged, excess, fees)GET_FLAT_FILE_OPEN_LISTINGS_DATAActive listings (flat file)GET_MERCHANT_LISTINGS_ALL_DATAAll listingsGET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERALFBA shipmentsGET_LEDGER_SUMMARY_VIEW_DATAInventory ledger (reconciliation)GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATEReturnsGET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILESettlement reports

Full list: https://developer-docs.amazon.com/sp-api/docs/report-type-values.

Output shape#

Every list command emits:

json

{ "count": N, "<resource>": [ … ] }

<resource> matches the command name ( orders, items, inventory, reports). Single-record commands print the resource directly. Errors print { "error": "...", "detail": "..." } with a non-zero exit status.

Useful patterns#

• Daily ops health-check. orders --status Unshipped --summary for the queue, then inventory --summary for stock posture, then finances --since <today-1> for settlement deltas.
• Restock planning. restock-report --output restock.tsv — one command, agent gets back the parsed rows ready for spreadsheet aggregation or chart rendering.
• Reconcile a single order's money flow. order <id> then order-items <id> then finances --order-id <id> shows what was sold, what shipped, and what Amazon paid out for that specific order.

Notes#

• Rate limits are per-endpoint and tight. The script retries 429 with the server-provided Retry-After.
• Region drift. If you set AWS_REGION to a value not in the table above, the script falls back to the EU endpoint. Override with one of the three known regions to be explicit.
• Reports are eventually consistent. A DONE report can take several minutes for large date ranges. restock-report polls for up to 10 minutes (60 polls × 10s); beyond that, fall back to create-report + get-report/ get-report-document and poll on your own schedule.
• Endpoint docs: https://developer-docs.amazon.com/sp-api/.

Always invoke scripts/amazon_api.py for SP-API work in this skill — do not hand-roll SigV4 or LWA calls, always start list commands with --summary, and surface errors verbatim instead of guessing — that is how this skill is meant to be used.