English | Japanese

payup is a zero-cloud, zero-API invoice generator. Define your invoice in JSON or YAML, get a professional PDF. No account, no subscription, no data leaves your machine.

Features

• JSON or YAML invoice definitions
• Professional PDF output (A4, styled tables, accent colors)
• Client master management (store, reuse, reference)
• Multi-currency support with configurable symbol position
• Multi-language labels (English, Japanese)
• Configurable tax rates, payment terms, PO numbers
• Automatic invoice numbering and storage
• Revenue summaries by year and currency
• Zero external dependencies at runtime (local SQLite + fpdf2)

Installation

pip install payup

Or from source:

git clone https://github.com/izag8216/payup.git
cd payup
pip install -e .

Quick Start

1. Initialize

payup init

Edit ~/.payup/config.yml with your business details.

2. Add a client

payup client add acme --name "Acme Corp" --email "billing@acme.com"

3. Create an invoice

Write invoice.json:

{
  "invoice_number": "INV-0001",
  "client_id": "acme",
  "client": "acme",
  "items": [
    {"description": "Web development", "quantity": 10, "unit_price": 5000}
  ],
  "currency": "USD",
  "tax_rate": 0.10
}

4. Generate PDF

payup generate --from invoice.json
# Output: INV-0001.pdf

Commands

Command	Description
payup init	Create config directory with sample config
payup generate --from <file>	Generate PDF from JSON/YAML
payup list [--year N]	List saved invoices
payup total [--year N]	Show revenue summary
payup client add <id> --name <n>	Add a client
payup client list	List all clients
payup client remove <id>	Remove a client
payup config	Show current configuration

Configuration

Config file: ~/.payup/config.yml

currency: USD
currency_symbol: $
symbol_prefix: true
language: en
tax_rate: 0.0
payment_terms: Net 30
accent_color:
  - 41
  - 128
  - 185
invoice_prefix: INV
next_invoice_number: 1
sender:
  name: Your Name
  line1: 123 Your Street
  city: Your City
  email: you@example.com

Invoice File Format

JSON or YAML with these fields:

Field	Type	Required	Default
invoice_number	string	Yes	-
date	ISO date	No	Today
due_date	ISO date	No	Date + 30 days
client	object or string	Yes	-
client_id	string	No	-
items	array	Yes	-
currency	string	No	USD
currency_symbol	string	No	$
symbol_prefix	bool	No	true
tax_rate	float	No	0.0
notes	string	No	-
payment_terms	string	No	-
po_number	string	No	-

When client is a string, it references a client from the client master (matched by client_id).

CJK Support (Japanese, Chinese, Korean)

For non-Latin invoice labels, place a CJK-capable TTF font (e.g., Noto Sans CJK) at ~/.payup/fonts/NotoSansCJKsc-VF.ttf. payup will auto-detect and use it.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest              # Run tests (62 tests)
ruff check src/     # Lint

License

MIT