Professional invoice generation for freelancers and small businesses. Generate beautiful invoices in seconds. No dependencies, no subscriptions, no cloud req...
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
Invoice Forge helps you:
Perfect for freelancers, consultants, indie creators, and small businesses who need invoicing that just works.
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
python invoice_clients.py add client001 "John Doe" "john@example.com" "123 Main St, City" "+1-555-0100"
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.
# 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
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
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
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
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
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
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
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
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
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
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"
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_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_SYMBOL = "$"
CURRENCY_CODE = "USD"
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 = {
"monthly_retainer": {
"description": "Monthly Retainer",
"items": [{"description": "...", "quantity": 1, "rate": 5000.00}],
"payment_terms": 15,
"notes": "...",
},
}
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:
{"client_id": "client001", "name": "John Doe", "email": "john@example.com", "address": "...", "phone": "...", "created_at": "...", "updated_at": "..."}
{"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", ...}
Keep your invoices under version control (git) for:
git init
git add data/ output/
git commit -m "January invoices"
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)"
If you bill the same thing regularly (monthly retainers, subscriptions), set up templates in config.json. Saves time and ensures consistency.
python invoice_report.py overdue
Set a reminder to run this every Monday morning. Follow up promptly.
Revenue by month helps with quarterly/annual tax filing:
python invoice_report.py revenue --period month
The HTML invoices are print-ready. Open in browser, print to PDF, send to clients.
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}")
# Clone or download
git clone <your-repo-url> 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
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 <type> 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 <name> <client> 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.
This is open-source software provided as-is under the MIT License. No support is guaranteed, but feel free to:
MIT License - see LICENSE file for details.
Created by Shadow Rose
quality-verified for production use.
v1.0.0 - Initial release
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.
| 🐛 Bug Reports | TheShadowyRose@proton.me |
| ☕ Ko-fi | ko-fi.com/theshadowrose |
| 🛒 Gumroad | shadowyrose.gumroad.com |
| @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
ZIP package — ready to use