amazon-taxes

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

1. In Amazon Seller Central, go to Reports > Tax Document Library
2. Download the Combined Sales Tax Report for the desired period
3. 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   # re-download even if cached

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   # install dependencies

For the SP-API path only, copy and fill in credentials:

cp .env.example .env
# Edit .env with your Amazon SP-API credentials

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.