| name | amazon-taxes |
| description | Process Amazon sales tax reports and generate per-state filing summaries from Seller Central CSV or SP-API data. |
| allowed-tools | Bash, Read |
| user-invocable | true |
| argument-hint | import report.csv --month 2026-03 | report --states WA,NC --quarter Q1-2026 |
amazon-taxes
CLI tool that processes Amazon sales tax reports and generates per-state filing summaries. Supports two data sources: manual CSV downloads from Seller Central or automated SP-API fetching.
Getting data
Option A: Manual CSV download
- In Amazon Seller Central, go to Reports > Tax Document Library
- Download the Combined Sales Tax Report for the desired period
- Import it:
uv run amazon-taxes import <file.csv> --quarter Q1-2026
uv run amazon-taxes import <file.csv> --month 2026-03
Option B: SP-API automated fetch (requires .env credentials)
uv run amazon-taxes pull --quarter Q1-2026
uv run amazon-taxes pull --quarter Q1-2026 --force
Data is normalized and cached to data/. Only re-pull with --force if you suspect stale data.
Generating reports
uv run amazon-taxes report --states WA,NC --quarter Q1-2026
uv run amazon-taxes report --states GA --year 2025
uv run amazon-taxes report --states OH --semi-annual H1-2026
uv run amazon-taxes report --states WA,NC,GA,OH,MN --month 2026-03
uv run amazon-taxes report --states WA --quarter Q1-2026 --format csv
uv run amazon-taxes report --states WA --quarter Q1-2026 --format csv --output report.csv
Required flags:
--states — comma-separated state codes (e.g., WA,NC,GA)
Period flags (exactly one required):
--quarter Q1-2026--month 2026-03--year 2025--semi-annual H1-2026
Output flags (optional):
--format csv — CSV output instead of terminal table--output <file> — write to file instead of stdout
Period formats
| Flag | Format | Example | Covers |
|---|
--quarter | Q{1-4}-YYYY | Q1-2026 | Jan-Mar 2026 |
--month | YYYY-MM | 2026-03 | March 2026 |
--year | YYYY | 2025 | Full year 2025 |
--semi-annual | H{1-2}-YYYY | H1-2026 | Jan-Jun 2026 |
Output formats
- Table (default): Rich terminal table with gross sales, tax collected, and tax owed per state
- CSV: Machine-readable output with columns:
state,period,gross_sales,mf_sales,taxable_sales,tax_collected_marketplace,tax_owed
Setup
uv sync
For the SP-API path only, copy and fill in credentials:
cp .env.example .env
Required .env variables: SP_API_REFRESH_TOKEN, SP_API_LWA_APP_ID, SP_API_LWA_CLIENT_SECRET, SP_API_AWS_ACCESS_KEY, SP_API_AWS_SECRET_KEY, SP_API_ROLE_ARN.
The manual CSV import path does not require any credentials.
When NOT to use this skill
- General tax advice or tax law questions — this tool generates reports, not advice
- Amazon Seller Central account issues — this is about tax data, not seller operations
- Non-Amazon marketplace tax data (eBay, Walmart, etc.) — only Amazon data is supported
- Bookkeeping, P&L, or general accounting questions beyond sales tax reporting
Error handling
- "No data cached" — Import a CSV or run
pull first
- "Missing SP-API credentials" — Check
.env file has all 6 required vars (see .env.example). Not needed for manual CSV import.
- Report times out on pull — SP-API reports can take 1-5 minutes. The CLI polls automatically with exponential backoff up to 30 minutes.
This skill provides tool capabilities only. Filing states, deadlines, frequencies, and business rules are your responsibility — bring your own context.
