Invoice Builder

---
name: invoice-builder
description: Use when generating an invoice PDF from line items and customer info. Triggers on "generate invoice", "create invoice PDF", "build an invoice", or pasted line-item data with seller/buyer info.
---

# Invoice Builder

Generate clean, single- or multi-page invoice PDFs that an accountant won't send back. Most invoice PDFs break on long line item descriptions, miss tax math edge cases, or push totals onto a second page where they get missed. Handle this deliberately.

## Required inputs

Before generating, confirm you have:

1. **Seller** — legal name, address, tax ID (VAT/EIN), bank/payment details
2. **Buyer** — legal name, billing address, optional VAT/tax ID, optional PO number
3. **Invoice metadata** — invoice number, issue date, due date (or net terms)
4. **Line items** — for each: description, quantity, unit price, tax rate, optional discount
5. **Currency** and **tax model** (per-line, single rate, or tax-exempt)

If anything required is missing (especially seller tax ID or buyer billing address), ask before generating. A missing tax ID makes the invoice non-deductible in many jurisdictions.

## Approach

Default: **HTML + print CSS, rendered via headless Chrome (puppeteer/playwright) or WeasyPrint**. This handles long descriptions, multi-page totals, and consistent typography across platforms.

Fallback if no PDF library is available: produce clean printable HTML with a `@media print` stylesheet and instruct the user to "Save as PDF" from a browser. Mention this fallback explicitly — don't pretend you generated a PDF when you generated HTML.

For programmatic Python-only environments: ReportLab Platypus with a Table flowable. Avoid raw canvas drawing for invoices — line item wrapping is the failure mode.

## Structure

Page 1 (and only page 1) header:
- Seller name + address top-left
- "INVOICE" + invoice number top-right
- Issue date, due date, PO number in a small metadata block

Body:
- Buyer billing address (left), shipping if different (right)
- Line items table: Description | Qty | Unit | Tax % | Line total
- Subtotal, tax breakdown by rate, discounts, **grand total in larger type**

Footer (every page):
- Payment instructions (bank/IBAN/SWIFT or payment link)
- Page X of Y
- Legal footer (seller registration number, jurisdiction)

## Style guidance

- Page size: A4 by default, US Letter if seller is US-based
- Margins: 18mm top/bottom, 15mm left/right
- Body type: 10pt, descriptions can wrap to 2-3 lines
- Total: 14pt bold, with a 1px rule above
- Use one accent color max; black text on white
- Numbers right-aligned in tables, monospace tabular figures so columns align

## Common pitfalls

- **Long descriptions** break naive templates. Set `white-space: normal` on description cells and `word-break: break-word` for URLs/SKUs.
- **Multi-page totals**: use `thead` repeating headers + a totals row with `page-break-inside: avoid`.
- **Tax rounding**: round per line, then sum — not the other way around. EU VAT auditors check this.
- **Currency formatting**: locale-aware (1.234,56 € vs $1,234.56). Don't hardcode.
- **Invoice number gaps**: if the user gives you a number, use it verbatim. Never auto-increment without permission.

## Output

Return the rendered PDF (or HTML if falling back). Always print a 1-line summary: invoice number, total, due date, page count — so the user can sanity-check before sending.