Building Invoice Generator

We built this skill so you don't have to debug @page rules at 2 AM or fight float precision errors in your billing scripts. If you're a working engineer tasked with generating invoices for construction firms, service providers, or any B2B operation, you know the drill: the data lives in a CSV or Excel sheet, the client expects a pristine PDF, and the gap between the two is a swamp of formatting edge cases.

We created the Building Invoice Generator skill to bridge that gap. It's a production-grade, multi-file workflow that validates your data schema, renders professional layouts using Jinja2, and exports batch PDFs with WeasyPrint. No headless Chrome overhead, no fragile Selenium scripts, just a deterministic pipeline that passes CI/CD checks and ships invoices on time.

The CSV-to-PDF Nightmare No One Talks About

You have the data. Your project manager exports a CSV with client_name, project_id, date, line_items, rate, hours, tax_rate, and discount. You need to turn that into a batch of PDF invoices that look like they came from a design agency, not a terminal.

Most engineers reach for a quick-and-dirty solution. They write a loop, dump strings into a PDF library, and hope for the best. That works until you hit pagination. WeasyPrint (and every print engine) respects CSS @page rules. Your line items span two pages. Your table header disappears on page two. Your currency formatting breaks when the locale changes. Suddenly, you're spending hours tweaking break-inside: avoid and fighting with WeasyPrint's HTML class initialization just to keep a table row intact.

Jinja2 solves the templating complexity, but only if you structure it right. Jinja is a fast, expressive, extensible templating engine ^[1]. It lets you write Python-like syntax for loops and logic, but you still need to handle currency filters, conditional tax logic, and minification for print. If you're generating hundreds of invoices, you can't afford a slow render loop. You need a stack that validates data before it touches the template engine, so a missing column doesn't crash your batch job halfway through.

If you're already building PDF infrastructure, check our Building Pdf Generator Service for a headless Chrome alternative when you need complex JavaScript rendering, but for invoice batches, the Jinja2 + WeasyPrint stack is lighter and faster.

What Bad Invoice Automation Costs Your Bottom Line

Ignoring the quality of your invoice generation workflow isn't just an annoyance; it's a liability.

1. Engineering Hours Bleed: Every hour you spend fixing a WeasyPrint pagination bug is an hour you aren't shipping features. A typical invoice script requires 20–40 hours of initial development and ongoing maintenance for edge cases like zero-value line items, multi-page tables, and varying tax jurisdictions. That's 40+ hours per quarter for a mid-sized firm. 2. Payment Delays: Clients pay based on accurate, professional invoices. If your PDF has a formatting error, a truncated table, or a wrong tax total, the client disputes the invoice. Disputes delay revenue by 30–60 days on average. In construction, where margins are thin, that cash flow gap can kill a project. 3. Data Integrity Risks: Without validation, bad data enters the render pipeline. A string in a rate column, a duplicate invoice ID, or a missing project_id can cause silent failures. You might generate a PDF with NaN tax values or duplicate line items. Catching these errors after generation means regenerating the batch, re-sending emails, and losing trust. 4. Scaling Costs: As your volume grows, so does the cost of manual fixes. A team processing 500 invoices a month can't afford to manually check each PDF. You need automation that scales linearly. If you're building a full billing ecosystem, the Invoice & Billing Systems Pack covers the downstream dunning and revenue recognition logic, but you still need a reliable generator at the core.

How a Construction Team Automates 500 Invoices Monthly

Imagine a mid-sized construction firm managing 200 active jobs. Every month, the accounting team exports a single Excel workbook with 500 rows of billing data. Each row represents a client, but each client has multiple line items (labor, materials, subcontracts). The requirement: generate 500 professional PDF invoices by Friday afternoon, with accurate tax calculations, proper pagination, and attachments for supporting documents.

Here's how the workflow executes with the skill installed:

Phase 1: Validation. The pipeline runs scripts/validate_invoices.py against the Excel file. Pandas loads the data with strict dtype enforcement. The script checks for required columns (client_name, project_id, rate, hours). It flags duplicates using allows_duplicate_labels=False. If the schema is violated, the script exits non-zero (sys.exit(1)), halting the pipeline before any rendering occurs. This prevents bad data from ever reaching the template engine. Phase 2: Rendering. Once validated, scripts/generate_invoices.py kicks in. It uses Pandas to group line items by project_id. For each group, it loads templates/invoice.html.j2. The template uses {% for %} loops to iterate over line items and {% if %} blocks for conditional tax logic. Jinja2's math expressions support addition and subtraction directly in templates [8], so the template calculates subtotal = rate hours and tax = subtotal tax_rate cleanly. The template also applies Jinja2 filters for currency formatting, ensuring $1,234.56 output regardless of input precision. The engine uses jinja2_htmlmin.minify_loader to minify the HTML, reducing payload size for WeasyPrint. Phase 3: PDF Export. WeasyPrint takes the rendered HTML and templates/styles.css. The CSS defines @page rules, table styling, and responsive print breakpoints. WeasyPrint's write_pdf method exports the batch. The script supports pdf_variant parameters, dynamic zoom, and attachments. Each invoice is saved as a separate PDF, ready for distribution.

Generating PDFs from dynamic HTML templates remains a common engineering challenge ^[2], but this stack handles it deterministically. Special placeholders in the template allow writing code similar to Python syntax ^[3], making the logic transparent and maintainable. A reference implementation from a 2024 GitHub Engineering blog post ^[4] highlights how modern templating engines have matured to handle complex document generation without heavy dependencies.

If your team also needs to notify clients, you can pair this with the Building Email Template Builder to generate responsive transactional emails that attach the generated PDFs.

The After-State: Validated Data, Crisp PDFs, Zero Regressions

Once you install the Building Invoice Generator skill, your invoice workflow transforms from a fragile script to a robust, CI/CD-ready pipeline.

Zero Schema Errors: scripts/validate_invoices.py catches missing columns, wrong dtypes, and duplicates before rendering. The pipeline fails fast with a clear error message. Professional Output: templates/invoice.html.j2 and templates/styles.css produce print-perfect PDFs. @page rules ensure consistent pagination. Tables stay intact. Currency formats are consistent. Fast Batch Processing: Pandas handles 10,000+ rows in seconds. Jinja2's speed ^[5] ensures the render loop doesn't bottleneck. WeasyPrint exports PDFs efficiently. Configurable Variants: The skill supports pdf_variant parameters, allowing you to generate draft invoices, final invoices, or client-specific layouts from the same template. CI/CD Ready: tests/validate.sh runs the validator against sample data and checks exit codes. You can integrate this into your GitHub Actions or GitLab CI pipeline to prevent bad data from reaching production. Extensible References: references/weasyprint-jinja2-core.md and references/pandas-data-pipeline.md provide embedded canonical knowledge on write_pdf parameters, Pandas groupby aggregations, and duplicate index management. You don't need to Google WeasyPrint docs every time you tweak a parameter.

If you're building a client portal, the Building Landing Page Generator can integrate with this skill to display invoice status and download links dynamically.

What's in the Building Invoice Generator Pack

This is a multi-file deliverable. Every file is designed to work together, enforce best practices, and ship production-grade code.

skill.md — Orchestrator skill defining the 3-phase invoice generation workflow (Validate -> Process -> Render). References all templates, scripts, validators, and references. Enforces the Jinja2 + WeasyPrint + Pandas stack for batch PDF generation. templates/invoice.html.j2 — Production-grade Jinja2 HTML template for professional invoices. Uses {% for %} loops for line items, {% if %} for conditional tax/discount logic, and Jinja2 filters for currency formatting. Structured for jinja2-htmlmin minification compatibility. templates/styles.css — WeasyPrint-optimized CSS for print layouts. Defines @page rules, table styling, and responsive print breakpoints. Ensures consistent pagination and professional typography across generated PDFs. scripts/generate_invoices.py — Core executable Python script. Uses pandas to load CSV/Excel data, jinja2_htmlmin.minify_loader to render templates, and weasyprint.HTML.write_pdf to export batch PDFs. Supports pdf_variant, attachments, and dynamic zoom. scripts/validate_invoices.py — Data validation script using pandas. Checks required columns, enforces dtypes via read_excel/read_csv, handles duplicates with allows_duplicate_labels=False, and exits non-zero (sys.exit(1)) on schema violations. references/weasyprint-jinja2-core.md — Embedded canonical knowledge from Context7. Covers jinja2-htmlmin minify_loader configuration, WeasyPrint HTML class initialization, write_pdf parameters (target, zoom, finisher), PDF attachments, and pdf_variant/form generation. references/pandas-data-pipeline.md — Embedded canonical knowledge from Context7. Documents pandas query/eval with @ local variable syntax, groupby aggregations, cut/qcut binning, read_excel dtype/na_values handling, and duplicate index management. examples/invoices.csv — Sample dataset for the worked example. Contains realistic construction/service provider fields: client_name, project_id, date, line_items, rate, hours, tax_rate, discount. Used to demonstrate batch processing and validation.

* tests/validate.sh — Executable bash validator. Runs the Python validator against the sample CSV, captures exit codes, and fails the pipeline if data integrity checks do not pass. Ensures CI/CD readiness.

Stop Debugging CSS at Midnight. Ship in Minutes.

You didn't become an engineer to write invoice scripts. You became an engineer to solve hard problems, not to fight WeasyPrint pagination bugs or debug Pandas dtypes.

The Building Invoice Generator skill gives you a validated, render-ready pipeline that produces professional PDFs from CSV/Excel data. It catches errors before they happen, formats invoices correctly, and scales to thousands of rows without breaking. Upgrade to Pro to install the skill and ship your next invoice batch in minutes, not days.

Stop X, start Y. Upgrade to Pro to install.