---
name: amazon-invoice
description: Generate tax invoices from Amazon Seller Central order data using browser extraction and PDF generation
requires: [amazon-shared]
---

# Amazon Invoice Generator

> **PREREQUISITE:** Read `../amazon-shared/SKILL.md` for marketplace
> TLD map, sign-in / Ziniao / OTP handling, and the hamburger-menu
> navigation pattern (used to reach Tax Document Library before
> running this generator).

Generate professional tax invoices for Amazon orders by extracting data from Seller Central and producing PDF invoices via ReportLab.

## Prerequisites

1. **Python deps are pre-installed** — the shared workspace venv already has `reportlab`. Just use `python` (it's on your PATH). If you get an import error, run: `uv pip install -r .claude/skills/amazon-invoice/requirements.txt`

2. **Resolve seller info** (company name, VAT/RFC numbers) — optional, try in order:
   1. **Store knowledge** — check the store profile directory (shown in your system context, e.g. `stores/<store-slug>/`) for `seller-info.md` or `notes.md` containing seller entity name and VAT numbers.
   2. **Order detail page** — Amazon Seller Central may show your seller/business info on the order page.
   3. **Ask the user** — if neither source has the info, ask once. If the user provides it, **save it** to the store directory's `seller-info.md` (e.g. `stores/<store-slug>/seller-info.md`) so future tasks can find it.
   4. **Proceed without** — the invoice script handles missing seller fields gracefully (omits the seller section). Do not block invoice generation over missing seller details.

**IMPORTANT**: Stay in your current working directory. Do NOT `cd` into the skill directory or any global path. Use relative paths for scripts and output.

## Determining the Country

You **always know the country** before generating an invoice. Get it from:

1. **Store metadata** — the `platform_countries` field in your store context tells you which countries this store operates in (e.g., `amazon: US, UK`). If the task targets a specific country, use `task_country`.
2. **Current Seller Central session** — you know which country/marketplace you are browsing because you selected it (Seller Central lets you toggle between countries within the same session).

The `country` field (2-letter ISO code) is **required** in the JSON you pass to the script. The script uses it to look up the correct tax rate and tax rules.

### Supported Countries & Default Tax Rates

The script has built-in tax rules for all Amazon marketplace countries:

| Country | Code | Tax | Rate | Prices on Order Page |
|---------|------|-----|------|---------------------|
| Saudi Arabia | SA | VAT | 15% | Include tax |
| UAE | AE | VAT | 5% | Include tax |
| Egypt | EG | VAT | 14% | Include tax |
| South Africa | ZA | VAT | 15% | Include tax |
| Turkey | TR | KDV | 20% | Include tax |
| UK | UK/GB | VAT | 20% | Include tax |
| Germany | DE | MwSt | 19% | Include tax |
| France | FR | TVA | 20% | Include tax |
| Italy | IT | IVA | 22% | Include tax |
| Spain | ES | IVA | 21% | Include tax |
| Netherlands | NL | BTW | 21% | Include tax |
| Poland | PL | VAT | 23% | Include tax |
| Sweden | SE | Moms | 25% | Include tax |
| Belgium | BE | BTW | 21% | Include tax |
| Ireland | IE | VAT | 23% | Include tax |
| Japan | JP | CT | 10% | Include tax |
| India | IN | GST | 18% | Include tax |
| Singapore | SG | GST | 9% | Include tax |
| Australia | AU | GST | 10% | Include tax |
| US | US | — | 0% | No tax |
| Canada | CA | GST | 5% | Exclude tax |
| Mexico | MX | IVA | 16% | Exclude tax |
| Brazil | BR | ICMS | 17% | Include tax |

**"Include tax"** means the prices shown on the order detail page already contain tax. The script back-calculates: `tax = gross × rate / (1 + rate)`.

**"Exclude tax"** means prices are pre-tax. The script adds tax on top: `tax = subtotal × rate`.

## Workflow

For each order ID provided:

### Step 1: Navigate to Order Detail

Go to Seller Central → Orders → Manage Orders → search by Order ID → click into the order detail page.

Make sure you are on the correct country/marketplace within Seller Central before extracting data.

### Step 2: Extract Order Data

From the order detail page, extract the data into this JSON structure. Pass **raw strings** exactly as shown on the page (e.g., `"USD 1,234.56"`) — the script parses them automatically.

```json
{
  "country": "US",
  "invoice_number": "<Order ID>",
  "date": "<order date, YYYY-MM-DD>",
  "bill_to": {
    "name": "<buyer name>",
    "entity": "<business name if present>",
    "vat": "<buyer VAT number if shown>",
    "rfc": "<buyer RFC if shown (Mexico)>",
    "trn": "<buyer TRN if shown, where applicable>",
    "address": "<full billing address>"
  },
  "ship_to": "<full shipping address>",
  "items": [
    {
      "description": "<product title>",
      "quantity": 1,
      "amount": "<total amount for this line item, e.g. 'USD 299.00'>"
    }
  ],
  "subtotal": "<if shown on page, else omit>",
  "tax": "<if shown on page, else omit>",
  "shipping_total": "<if shown, else omit>",
  "promotion": "<if shown, else omit>",
  "refund": "<refund amount shown on the order page as an absolute value (e.g. a row labeled 'Refund: -USD 12.00' becomes '12.00'); omit if none>",
  "total": "<total as shown on page>",
  "amount_paid": "<if shown, else omit>",
  "currency": "USD",
  "seller_entity": "<from store knowledge, if available>",
  "seller_vat": "<from store knowledge, if available>",
  "seller_rfc": "<from store knowledge, if available for Mexico>",
  "store": "<store name>"
}
```

**Required fields**: `country`, `invoice_number`, `items` (with at least `description` and `amount` per item).

All other fields are optional — the script derives what's missing.

**Note on items**: The PDF shows a simplified 3-column table (Item, Quantity, Amount). The `amount` field should be the **total line item amount** (quantity × unit price) as shown on the order page.

### Step 3: Let the Script Handle Calculations

**You do NOT need to calculate tax yourself.** The `generate_invoice.py` script:

1. **Parses currency strings** — `"USD 1,234.56"` → `1234.56`
2. **Looks up tax rules by country code** — the `country` field you provide
3. **Prioritizes page values** — if the order page shows explicit subtotal + tax + total **and no refund is present**, the script uses those instead of calculating
4. **Handles refunds** — if a refund is provided, the script always recomputes from components (`items + shipping − promotion − refund`) because Amazon's order page shows subtotal **before** refund and total **after** refund, so those page values are mutually inconsistent when a refund exists. The derived gross matches the Item total line the customer actually paid.
5. **Falls back to country rules** — if page values are incomplete, calculates tax from item totals using the country's rate and inclusive/exclusive model

Just extract what you see on the page and pass it through. For each item, provide the **total line amount** (as shown on the order page) rather than unit price.

### Step 4: Add Seller Info (if available)

If seller info was resolved in the Prerequisites step, populate:
- `seller_entity`: company legal name
- `seller_vat`: VAT number for the relevant country
- `seller_rfc`: RFC for Mexico

If no seller info was found, omit these fields — the script handles missing seller data gracefully.

### Step 5: Generate PDF

```bash
echo '<json_string>' | python .claude/skills/amazon-invoice/generate_invoice.py \
  --output ./invoice_{order_id}.pdf
```

The script outputs the file path to stdout. Output goes to the current working directory (the task workspace).

### Step 6: Save Discovered Information

If you found seller entity details (company name, VAT/TRN numbers) during this task that are NOT already saved in the store's knowledge directory:
- Save them to `stores/<store-slug>/seller-info.md` using the Write tool
- This persists across tasks so you won't need to look it up again

### Step 7: Report Result

After generating, report the file path to the user. If multiple orders were requested, summarize all generated invoices.

## Batch Mode

If the user provides multiple order IDs (comma-separated, space-separated, or one per line), loop steps 1-6 for each order ID. Generate separate PDFs for each order.

## Error Handling

- If an order ID is not found in Seller Central, skip it and report the error
- If Seller Central requires login, wait for auto-fill (Ziniao) or ask the user
- If seller info is missing, skip it — the script handles missing fields gracefully
- The script exits with an error if `country` is missing — always provide it
