Invoice Generator Pro

Generates professional invoices from time tracking data with support for hourly, fixed-rate, and milestone billing. Handles multiple currencies, automatic tax calculations, late payment terms, and PDF export. Designed for freelancers, consultants, and small business owners who need polished invoices without a monthly SaaS subscription.

Supported Platforms & Integrations

Platform	Integration Type	Features
Toggl Track	CSV/API import	Auto-import tracked hours, map projects to clients, round time entries
Harvest	CSV export	Import time entries with notes, billable flags, project mappings
Clockify	JSON/CSV import	Pull detailed time reports, apply billing rates per project
Google Sheets	Direct read	Read line items, rates, and client info from structured spreadsheets
Stripe	Payment links	Generate Stripe payment links embedded in invoice for instant payment
Wave Accounting	CSV export	Export invoice data compatible with Wave's import format

When to Use

• End-of-month billing: Generate invoices for all clients from your accumulated time tracking data in one batch run
• Milestone invoices: Create invoices tied to project deliverables with percentage-based billing schedules
• Multi-currency clients: Bill international clients in their local currency with automatic exchange rate lookup
• Recurring retainers: Generate standard monthly retainer invoices with consistent line items and auto-incrementing invoice numbers
• Tax season preparation: Produce a complete set of invoices for a date range with tax summaries for your accountant
• Late payment follow-up: Re-generate overdue invoices with updated due dates, interest calculations, and payment reminder language

Alternatives to consider:

• For full accounting suites with payroll, use FreshBooks or QuickBooks directly
• For simple one-off invoices without time tracking, a Google Docs template may suffice
• For enterprise billing with subscription management, consider Chargebee or Recurly

Quick Start

Copy
invoice:
  client: "Acme Corp"
  client_email: "[email protected]"
  billing_type: "hourly"           # hourly | fixed | milestone
  currency: "USD"
  tax_rate: 0.08
  payment_terms: 30                 # days
  time_source: "toggl"              # toggl | harvest | clockify | sheets | manual
  date_range: "2026-02-01..2026-02-28"
  line_items:                       # manual override or supplement
    - description: "API Development"
      hours: 42.5
      rate: 125.00
    - description: "Code Review"
      hours: 8.0
      rate: 125.00
  output_format: "pdf"              # pdf | html | markdown
  output_path: "./invoices/"

Example prompt:

Generate an invoice for Acme Corp for February 2026. Pull my Toggl time entries
for project "Acme API" and bill at $125/hour. Apply 8% sales tax. Payment due
in 30 days. Export as PDF to ./invoices/

Example output:

Invoice #INV-2026-0024 generated successfully.

  Client:      Acme Corp
  Period:      Feb 1 - Feb 28, 2026
  Subtotal:    $6,312.50 (50.5 hours x $125.00/hr)
  Tax (8%):    $505.00
  Total Due:   $6,817.50
  Due Date:    March 30, 2026
  Payment:     Net 30

  Saved to: ./invoices/INV-2026-0024-acme-corp.pdf
  Payment link: https://pay.stripe.com/inv_xxxx (if Stripe configured)

Advanced Configuration

Platform-specific settings:

For Toggl Track integration, set your API token in environment or config:

Copy
toggl:
  api_token: "${TOGGL_API_TOKEN}"
  workspace_id: "7654321"
  rounding: "up_15"          # round to nearest 15 min, always up
  billable_only: true
  project_mapping:
    "Acme API": "Acme Corp"
    "Beta Dashboard": "Beta Inc"

For multi-currency with exchange rates:

Copy
currency:
  base: "USD"
  auto_exchange: true
  exchange_source: "ecb"     # European Central Bank daily rates
  lock_rate_on_generate: true

Full parameter reference:

Parameter	Type	Default	Description
invoice_prefix	string	INV	Prefix for invoice numbers
auto_number	boolean	true	Auto-increment invoice numbers from last generated
currency	string	USD	ISO 4217 currency code
tax_rate	float	0.0	Tax rate as decimal (0.08 = 8%)
tax_label	string	Sales Tax	Label shown on invoice for tax line
payment_terms	integer	30	Days until payment is due
late_fee_rate	float	0.015	Monthly interest rate on overdue amounts
rounding	string	nearest_15	Time rounding: none, nearest_15, up_15, nearest_30
logo_path	string	null	Path to company logo for PDF header
sender_info	object	{}	Your business name, address, tax ID
notes	string	""	Footer notes (bank details, thank you message)
output_format	string	pdf	Output: pdf, html, markdown, json

Core Concepts

Concept	Description
Billing Type	Hourly bills by tracked time x rate; Fixed bills a flat project fee; Milestone bills percentages at deliverable completion
Invoice Numbering	Sequential numbering with configurable prefix and year grouping (INV-2026-0001) persisted in .invoice-state.json
Time Rounding	Rounds individual time entries before summing — matches common freelance practice of billing in 15-minute increments
Tax Calculation	Applied per line item or on subtotal; supports compound tax (tax-on-tax) for jurisdictions that require it
Payment Terms	Net-N days from invoice date; configurable late fee calculations with grace period support

                    Invoice Generation Pipeline

  Time Source           Processing              Output
  +-----------+    +------------------+    +--------------+
  | Toggl     |--->|                  |--->| PDF File     |
  | Harvest   |--->|  Rate Mapping    |    | HTML File    |
  | Clockify  |--->|  Tax Calculation |--->| Markdown     |
  | Sheets    |--->|  Rounding        |    | JSON Data    |
  | Manual    |--->|  Numbering       |--->| Stripe Link  |
  +-----------+    +------------------+    +--------------+
                          |
                   .invoice-state.json
                   (sequence tracking)

Workflow Examples

Scenario 1: Monthly client billing batch

Input:  "Generate invoices for all active clients for February 2026
         using Toggl data. Apply each client's configured rate."

Output: Generated 4 invoices:
        INV-2026-0024  Acme Corp       $6,817.50  (50.5 hrs)
        INV-2026-0025  Beta Inc        $3,240.00  (27.0 hrs)
        INV-2026-0026  Gamma LLC       $2,000.00  (fixed)
        INV-2026-0027  Delta Partners  $4,500.00  (milestone 2/4)
        
        Total billable: $16,557.50
        All PDFs saved to ./invoices/2026-02/

Scenario 2: Milestone-based project invoice

Input:  "Create a milestone invoice for Project Atlas with Delta Partners.
         Milestone 2 of 4 complete: 'Backend API delivered'. 
         Total project: $18,000. This milestone is 25%."

Output: Invoice #INV-2026-0026
        Project Atlas - Milestone 2 of 4
        Deliverable: Backend API delivered
        Milestone amount: $4,500.00 (25% of $18,000)
        Previous billed: $4,500.00 (Milestone 1)
        Remaining: $9,000.00 (Milestones 3-4)
        Tax (8%): $360.00
        Total due: $4,860.00

Scenario 3: Overdue invoice with late fees

Input:  "Regenerate INV-2026-0019 for Omega Ltd as overdue. Original
         due date was Jan 15. Apply 1.5% monthly late fee."

Output: Invoice #INV-2026-0019-R1 (Revised)
        OVERDUE - Originally due January 15, 2026
        Original amount: $3,750.00
        Days overdue: 59
        Late fee (1.5%/mo x 1.97 months): $110.81
        Total now due: $3,860.81
        New payment deadline: March 25, 2026

Best Practices

1. Keep client configs in a dedicated file: Store client names, addresses, rates, and tax settings in a clients.yaml file so you never retype them. Reference by client slug in your invoice commands.

2. Lock exchange rates at generation time: When billing in foreign currencies, always save the exchange rate used on the invoice. This prevents disputes and ensures your accounting matches the invoice amounts.

3. Use consistent invoice numbering: Never manually set invoice numbers. Let the auto-incrementing system maintain sequence integrity. Gaps in numbering can raise red flags during audits.

4. Include payment instructions in notes: Always configure the notes field with your bank transfer details, PayPal address, or Stripe payment link. The easier you make it to pay, the faster you get paid.

5. Archive generated invoices with data: Keep both the PDF and the JSON data file for each invoice. The JSON preserves the exact line items, rates, and calculations for future reference, disputes, or tax reporting.

Common Issues

Time entries not matching expected hours Toggl and Harvest may include non-billable entries by default. Ensure billable_only: true is set in your time source config. Also verify that project name mappings are exact matches — "Acme API" is not "Acme Api".

PDF generation fails or looks broken PDF export requires wkhtmltopdf or a Puppeteer-compatible Chrome installation. Run which wkhtmltopdf or verify Chrome is accessible. For minimal environments, use html or markdown output and convert separately.

Tax calculation seems wrong on multi-line invoices By default, tax is calculated on the subtotal (after summing all line items). If your jurisdiction requires per-line-item tax calculation with rounding, set tax_mode: per_item in your config. The difference is usually pennies but matters for compliance.

Privacy & Data Handling

• Client data stays local: All client information, rates, and invoice history remain in your local project directory. Nothing is transmitted to external services unless you explicitly configure Stripe or email integration.
• Time tracking API tokens: If using Toggl/Harvest/Clockify integration, API tokens are read from environment variables — never hardcode them in config files. Add .env to your .gitignore.
• Invoice PDFs: Generated PDFs contain business and client information. Store them in a directory excluded from version control if your repo is public. Use ./invoices/ added to .gitignore.
• Payment links: Stripe payment links are generated via your Stripe API key. Ensure you use restricted keys with only invoice-related permissions.
• Data retention: The .invoice-state.json file tracks only invoice numbers and dates — no financial amounts or client details are stored in the state file.