Invoice Forge

Invoice Forge Professional Invoice Generator

Professional invoice generation for freelancers and small businesses. Generate beautiful invoices in seconds. No dependencies, no subscriptions, no cloud required. Clean Python code.

Professional invoice generation for freelancers and small businesses.

Generate beautiful, professional invoices in seconds. No dependencies, no subscriptions, no cloud required. Just clean Python code that works.

Created by Shadow Rose • quality-verified • MIT License

What It Does

Invoice Forge helps you:

Perfect for freelancers, consultants, indie creators, and small businesses who need invoicing that just works.

Quick Start

1. Set Up Your Configuration

Copy the example config and customize it:

cp config_example.json config.json

Edit config.json with your business details:

BUSINESS_NAME = "Acme Consulting"
BUSINESS_EMAIL = "billing@acme.com"
CURRENCY_SYMBOL = "$"
DEFAULT_PAYMENT_TERMS = 30  # Net 30
TAX_RATES = {"sales_tax": 0.08}  # 8% sales tax

2. Add a Client

python invoice_clients.py add client001 "John Doe" "john@example.com" "123 Main St, City" "+1-555-0100"

3. Create an Invoice

python invoice_forge.py create client001 \
  --item "Web Design Services" 1 2500.00 \
  --item "Hosting Setup" 1 500.00 \
  --terms 30

This creates an invoice, saves it as HTML in the output/ folder, and records it in your ledger.

4. View Your Invoices

# List all invoices
python invoice_forge.py list
See summary stats
python invoice_report.py summary
Check for overdue invoices
python invoice_report.py overdue

Features

Client Management

Store client details once, reuse forever:

# Add a client
python invoice_clients.py add acme "Acme Corp" "billing@acme.com"
List all clients
python invoice_clients.py list
Search clients
python invoice_clients.py list "acme"
Update client info
python invoice_clients.py update acme phone="+1-555-1234"
Get client details
python invoice_clients.py get acme

Invoice Generation

Create invoices with multiple line items, taxes, and discounts:

# Basic invoice
python invoice_forge.py create client001 \
  --item "Consulting" 10 150.00 \
  --item "Expenses" 1 250.00
With discount
python invoice_forge.py create client001 \
  --item "Web Development" 40 125.00 \
  --discount-percent 10
With custom terms
python invoice_forge.py create client001 \
  --item "Design Work" 1 5000.00 \
  --terms 15 \
  --notes "Thank you for your business!"
Custom invoice date
python invoice_forge.py create client001 \
  --item "Monthly Retainer" 1 3000.00 \
  --date 2024-01-01

Output Formats

Generate invoices in multiple formats:

# HTML (default - professional, print-ready)
python invoice_forge.py create client001 --item "Service" 1 1000 --format html
Markdown (for version control, notes)
python invoice_forge.py create client001 --item "Service" 1 1000 --format markdown
Plain Text (for email, terminal display)
python invoice_forge.py create client001 --item "Service" 1 1000 --format text

Payment Tracking

Update invoice status as payments come in:

# Mark as paid
python invoice_forge.py status INV-0001 paid
Mark as cancelled
python invoice_forge.py status INV-0002 cancelled
List by status
python invoice_forge.py list --status pending
python invoice_forge.py list --status paid

Recurring Templates

Set up templates for regular invoices:

Edit config.json:

RECURRING_TEMPLATES = {
    "monthly_retainer": {
        "items": [
            {"description": "Monthly Retainer", "quantity": 1, "rate": 5000.00}
        ],
        "payment_terms": 15,
        "notes": "Monthly retainer for ongoing services.",
    },
}

Then use it:

python invoice_forge.py template monthly_retainer client001

Reports & Analytics

Get insights into your business:

# Overall summary
python invoice_report.py summary
Client-specific summary
python invoice_report.py client client001
Overdue invoices
python invoice_report.py overdue
Revenue by month
python invoice_report.py revenue --period month
Top clients by revenue
python invoice_report.py top --limit 10
Aging report (who owes what for how long)
python invoice_report.py aging

Use Cases

Freelance Consultants

Track client hours, generate invoices weekly or monthly, monitor who's paid and who hasn't.

python invoice_forge.py create client001 \
  --item "Strategy Consulting - Week of Jan 15" 20 200.00 \
  --terms 15

Digital Product Sellers

Invoice for one-time purchases, custom work, or licensing fees.

python invoice_forge.py create client002 \
  --item "Premium License - VideoEdit Pro" 1 499.00 \
  --item "Priority Support (1 year)" 1 99.00

Small Agencies

Manage multiple clients, track monthly retainers, generate reports for accounting.

# Set up recurring template in config.json
python invoice_forge.py template monthly_retainer agency_client_001
python invoice_forge.py template monthly_retainer agency_client_002
Review outstanding balances
python invoice_report.py aging

Service Providers

Track project-based work with multiple line items and milestones.

python invoice_forge.py create startup_co \
  --item "Website Design - Phase 1" 1 3500.00 \
  --item "Logo Design" 1 800.00 \
  --item "Brand Guidelines Document" 1 500.00 \
  --discount-percent 5 \
  --notes "Milestone 1 of 3 - Design Phase"

Configuration Reference

Business Profile

BUSINESS_NAME = "Your Business Name"
BUSINESS_ADDRESS = """123 Main Street
Suite 456
City, State 12345"""
BUSINESS_EMAIL = "billing@yourbusiness.com"
BUSINESS_PHONE = "+1 (555) 123-4567"
BUSINESS_LOGO = None  # Path to logo image (optional)
PAYMENT_DETAILS = """Bank Transfer: ...
PayPal: billing@yourbusiness.com"""

Invoice Settings

INVOICE_PREFIX = "INV-"  # Invoice number prefix
INVOICE_START = 1        # Starting number
INVOICE_PADDING = 4      # Zero-pad to 4 digits (INV-0001)
DEFAULT_PAYMENT_TERMS = 30  # Net 30

Currency

CURRENCY_SYMBOL = "$"
CURRENCY_CODE = "USD"

Taxes

TAX_RATES = {
    "sales_tax": 0.08,  # 8%
    "vat": 0.20,        # 20%
}
DEFAULT_TAX_TYPE = "sales_tax"
TAX_LABELS = {
    "sales_tax": "Sales Tax",
    "vat": "VAT",
}

Recurring Templates

RECURRING_TEMPLATES = {
    "monthly_retainer": {
        "description": "Monthly Retainer",
        "items": [{"description": "...", "quantity": 1, "rate": 5000.00}],
        "payment_terms": 15,
        "notes": "...",
    },
}

File Structure

invoice-forge/
├── config_example.json         # Configuration template
├── config.json                 # Your config (create from example)
├── invoice_forge.py          # Main invoice engine
├── invoice_clients.py        # Client management
├── invoice_report.py         # Reports and analytics
├── invoice_template.py       # HTML/Markdown/Text rendering
├── data/
│   ├── clients.jsonl         # Client database
│   └── invoices.jsonl        # Invoice ledger
└── output/
    ├── INV-0001.html         # Generated invoices
    ├── INV-0002.html
    └── ...

All data is stored as JSONL (JSON Lines) for:

Data Format

Clients (data/clients.jsonl)

{"client_id": "client001", "name": "John Doe", "email": "john@example.com", "address": "...", "phone": "...", "created_at": "...", "updated_at": "..."}

Invoices (data/invoices.jsonl)

{"invoice_number": "INV-0001", "invoice_date": "2024-01-15", "due_date": "2024-02-14", "client": {...}, "items": [...], "subtotal": 3000.00, "tax_amount": 240.00, "total": 3240.00, "status": "pending", ...}

Tips & Best Practices

Version Control Your Invoices

Keep your invoices under version control (git) for:

git init
git add data/ output/
git commit -m "January invoices"

Backup Regularly

The data/ folder contains your entire business ledger. Back it up!

# Simple backup
cp -r data/ data-backup-$(date +%Y%m%d)
Or use git
git add data/
git commit -m "Backup $(date)"

Use Recurring Templates

If you bill the same thing regularly (monthly retainers, subscriptions), set up templates in config.json. Saves time and ensures consistency.

Check for Overdue Invoices Weekly

python invoice_report.py overdue

Set a reminder to run this every Monday morning. Follow up promptly.

Generate Tax Reports

Revenue by month helps with quarterly/annual tax filing:

python invoice_report.py revenue --period month

Print-to-PDF for Clients

The HTML invoices are print-ready. Open in browser, print to PDF, send to clients.

Python API

You can also use Invoice Forge as a library:

from invoice_forge import InvoiceForge
Initialize
forge = InvoiceForge()
Create invoice
invoice = forge.create_invoice(
    client_id="client001",
    items=[
        {"description": "Web Design", "quantity": 1, "rate": 2500.00},
        {"description": "Hosting Setup", "quantity": 1, "rate": 500.00},
    ],
    discount={"type": "percent", "value": 10},
    notes="Thank you for your business!",
)
Render as HTML
html = forge.render_invoice(invoice, format="html")
Save to file
filepath = forge.save_rendered_invoice(invoice, format="html")
print(f"Invoice saved to: {filepath}")

Client management:

from invoice_clients import ClientManager
Initialize
clients = ClientManager()
Add client
client = clients.add_client(
    client_id="client001",
    name="John Doe",
    email="john@example.com",
    address="123 Main St",
    phone="+1-555-0100",
)
Get client
client = clients.get_client("client001")
List all clients
all_clients = clients.list_clients()
Search clients
results = clients.list_clients(search="john")

Reports:

from invoice_report import InvoiceReporter
Initialize
reporter = InvoiceReporter()
Overall summary
summary = reporter.get_overall_summary()
print(f"Total invoiced: ${summary['total_invoiced']:,.2f}")
Overdue invoices
overdue = reporter.get_overdue_invoices()
print(f"{len(overdue)} invoice(s) overdue")
Revenue by month
revenue = reporter.get_revenue_by_period("month")
for month, amount in revenue.items():
    print(f"{month}: ${amount:,.2f}")

Requirements

Installation

# Clone or download
git clone  invoice-forge
cd invoice-forge
Set up config
cp config_example.json config.json
Edit config.json with your business details
Start invoicing!
python invoice_clients.py add client001 "John Doe" "john@example.com"
python invoice_forge.py create client001 --item "Service" 1 1000.00

FAQ

Q: Where is my data stored? A: All data is in the data/ folder as JSONL files. Human-readable, version-control friendly.

Q: Can I customize the invoice template? A: Yes! Edit invoice_template.py to change the HTML/CSS. The template is clean and well-commented.

Q: How do I handle multiple tax rates? A: Define them in config.json under TAX_RATES, then specify --tax when creating invoices.

Q: Can I add a logo? A: Yes! Set BUSINESS_LOGO = "logo.png" in config.json. The logo will be embedded in HTML invoices.

Q: How do I email invoices? A: Invoice Forge generates the invoice files; emailing is separate. Use your email client or a script to send the HTML files as attachments.

Q: Can I export to PDF directly? A: The HTML template is print-ready. Open in browser, print to PDF. For automation, use a tool like wkhtmltopdf or headless Chrome.

Q: What about recurring subscriptions? A: Set up templates in config.json, then use python invoice_forge.py template to generate them quickly.

Q: How do I migrate to a different system later? A: Data is stored as JSONL (one JSON object per line). Easy to parse and import into any other system.

Support

This is open-source software provided as-is under the MIT License. No support is guaranteed, but feel free to:

License

MIT License - see LICENSE file for details.

Created by Shadow Rose quality-verified for production use.

Changelog

v1.0.0 - Initial release

⚠️ Disclaimer

This software is provided "AS IS", without warranty of any kind, express or implied.

USE AT YOUR OWN RISK.

By downloading, installing, or using this software, you acknowledge that you have read this disclaimer and agree to use the software entirely at your own risk.

DATA DISCLAIMER: This software processes and stores data locally on your system. The author(s) are not responsible for data loss, corruption, or unauthorized access resulting from software bugs, system failures, or user error. Always maintain independent backups of important data. This software does not transmit data externally unless explicitly configured by the user.

Support & Links

| | | |---|---| | 🐛 Bug Reports | TheShadowyRose@proton.me | | ☕ Ko-fi | ko-fi.com/theshadowrose | | 🛒 Gumroad | shadowyrose.gumroad.com | | 🐦 Twitter | @TheShadowyRose | | 🐙 GitHub | github.com/TheShadowRose | | 🧠 PromptBase | promptbase.com/profile/shadowrose |

*Built with OpenClaw — thank you for making this possible.*

🛠️ Need something custom? Custom OpenClaw agents & skills starting at $500. If you can describe it, I can build it. → Hire me on Fiverr

1. Set Up Your Configuration

Copy the example config and customize it:

cp config_example.json config.json

Edit config.json with your business details:

BUSINESS_NAME = "Acme Consulting"
BUSINESS_EMAIL = "billing@acme.com"
CURRENCY_SYMBOL = "$"
DEFAULT_PAYMENT_TERMS = 30  # Net 30
TAX_RATES = {"sales_tax": 0.08}  # 8% sales tax

2. Add a Client

python invoice_clients.py add client001 "John Doe" "john@example.com" "123 Main St, City" "+1-555-0100"

3. Create an Invoice

python invoice_forge.py create client001 \
  --item "Web Design Services" 1 2500.00 \
  --item "Hosting Setup" 1 500.00 \
  --terms 30

This creates an invoice, saves it as HTML in the output/ folder, and records it in your ledger.

4. View Your Invoices

# List all invoices
python invoice_forge.py list
See summary stats
python invoice_report.py summary
Check for overdue invoices
python invoice_report.py overdue

Q: Where is my data stored? A: All data is in the data/ folder as JSONL files. Human-readable, version-control friendly.

Q: Can I customize the invoice template? A: Yes! Edit invoice_template.py to change the HTML/CSS. The template is clean and well-commented.

Q: How do I handle multiple tax rates? A: Define them in config.json under TAX_RATES, then specify --tax when creating invoices.

Q: Can I add a logo? A: Yes! Set BUSINESS_LOGO = "logo.png" in config.json. The logo will be embedded in HTML invoices.

Q: How do I email invoices? A: Invoice Forge generates the invoice files; emailing is separate. Use your email client or a script to send the HTML files as attachments.

Q: Can I export to PDF directly? A: The HTML template is print-ready. Open in browser, print to PDF. For automation, use a tool like wkhtmltopdf or headless Chrome.

Q: What about recurring subscriptions? A: Set up templates in config.json, then use python invoice_forge.py template to generate them quickly.

Q: How do I migrate to a different system later? A: Data is stored as JSONL (one JSON object per line). Easy to parse and import into any other system.