branded-invoice-kit

v1.0.0 MIT business updated 2026-09-27

Generate a branded, print-ready HTML invoice from JSON — bill-to block, line items, subtotal, tax, amount due, payment terms. Use when you need a professional invoice you can print or email without opening a spreadsheet or an invoicing app.

$ skillbank install branded-invoice-kit@1.0.0
# pins exactly 1.0.0 · README + changelog included

Branded Invoice Kit

Overview

Describe an invoice in JSON and scripts/invoice.py turns it into a self-contained HTML invoice: your brand header, the bill-to block, line items with quantities and unit prices, subtotal, tax computed from your tax rate, a bold Amount due, payment terms, and an optional notes line. Inline CSS and @media print rules so it prints cleanly from any browser. Standard library only; the totals are computed in the script, not by hand.

Installation

1. Copy the branded-invoice-kit/ directory anywhere convenient. 2. Make the script executable (Unix):


   chmod +x scripts/invoice.py

No pip install needed — standard library only.

Configuration

Two JSON files. See references/invoice-schema.md for the full field list.

invoice.json — the invoice itself:


{
  "invoice_number": "2026-0101",
  "issue_date": "2026-10-01",
  "due_date": "2026-10-31",
  "bill_to": {
    "name": "Robert Chen",
    "address": "1420 Birch Lane, Allentown, PA 18104",
    "email": "r.chen@example.com"
  },
  "line_items": [
    {"description": "Drain cleaning, main line", "quantity": 1, "unit_price": 189.00},
    {"description": "Faucet replacement, kitchen", "quantity": 2, "unit_price": 85.50}
  ],
  "tax_rate": 6,
  "payment_terms": "Net 30",
  "notes": "Thank you for your business."
}

brand.json — your brand kit (same shape as the proposal builder):


{
  "business_name": "Maple & Main Plumbing",
  "tagline": "Fast, honest plumbing",
  "colors": {"primary": "#0f4c81", "accent": "#f2a03d"}
}

Colors are optional — missing entries fall back to neutral defaults, so {"business_name": "My Co"} works on its own. tax_rate is a percentage (6 means 6%); quantity and unit_price must be numbers.

Inputs

scripts/invoice.py --invoice <invoice.json> --brand <brand.json> --out <invoice.html>

| Flag | Required | Description | |-------------|----------|----------------------------------------------| | --invoice | yes | Path to the invoice JSON file. | | --brand | yes | Path to the brand JSON file. | | --out | yes | Path to write the HTML invoice to. |

The script validates both files exist and parse as JSON before doing any work, rejects empty or non-numeric line items with a plain-English error, and exits nonzero without tracebacks. All text is HTML-escaped.

Worked example


$ ./scripts/invoice.py \
    --invoice references/sample-invoice.json \
    --brand references/sample-brand.json \
    --out invoice.html
wrote invoice.html (subtotal=$480.00 tax=$28.80 due=$508.80)

$ grep -o 'Amount due' invoice.html
Amount due

The sample invoice has 3 line items at a 6% tax rate: $189.00 + 2×$85.50 + $120.00 = $480.00 subtotal, $28.80 tax, $508.80 amount due — the script prints all three so you can spot-check the math before sending. Open invoice.html in a browser to print or save as PDF.

Safety notes

This skill is a local document generator: it reads two JSON files and writes one HTML file. It never uploads anything, never makes network calls, and never runs remote commands. It computes the totals for you, but you're the bookkeeper — confirm the amounts against your own records before billing anyone.

Version history

1.0.0 — 2026-09-27

  • Initial release: scripts/invoice.py builds a self-contained,
  • print-ready HTML invoice (bill-to, line items, subtotal/tax/amount-due computed from --invoice JSON, payment terms) from --invoice + --brand JSON.

  • Invalid JSON, empty item lists, and non-numeric quantities/prices exit
  • nonzero with a plain error message.

  • All invoice text HTML-escaped; brand colors fall back to sane defaults.

← back to catalog