Manual

1 · Getting started

1. Create a company from the dashboard. Defaults are tuned for South Africa: ZAR, en-ZA, 15% VAT, Cape Town, Western Cape.
2. Issue an invoice. The form picker auto-fills clients and products you've already saved.
3. Mark invoices as Paid when payment lands.
4. Open the Ledger tab for a printable running balance, or Statements to send a client their own statement of account.

2 · Companies

Every record lives under a company. Each one has its own:

• Branding — logo, brand and accent colors used on every PDF.
• Tax rules — currency, locale, default VAT, payment terms.
• Numbering — independent invoice and credit note counters with custom prefixes.
• Banking — bank, account, branch code, SWIFT/BIC and optional IBAN, all printed in the PDF footer.
• Optional password — see the next section.

3 · Passwords (optional)

• Each company can carry an optional password. When set, every per-company page requires the passphrase before it loads.
• Passwords are hashed with scrypt before they touch the database. The unlock state lives in an HMAC-signed cookie that lasts 12 hours per browser.
• Set or change it in the company form's Access protection section. Tick Remove password protection when editing to clear it.
• The "Lock" button on the company page wipes that company from the cookie immediately.

4 · Invoices

1. Click + New invoice on the company page.
2. Pick an existing client or fill the bill-to fields manually.
3. For each line, pick a product or write a custom description. Quantity and unit price recalc live.
4. If you switch the currency away from the company default, a live FX rate appears with a one-click "Convert line items" button (powered by open.er-api.com, no API key required).
5. Issue the invoice. The number is generated as PREFIX-YEAR-####. The FX rate at issue time is captured on the document.
6. Mark the invoice as Paid when payment arrives — that removes it from the open balance on ledgers and statements.

5 · Credit notes

Credit notes work the same as invoices, with two differences:

• You can link one to the original invoice it relates to — the relation is shown on both records.
• All amounts are shown as negatives on screen and on the PDF, and credited totals are subtracted on the ledger and statements.

6 · Ledger reports

The ledger is a chronological journal of every invoice and credit note for a company, with a running outstanding balance.

• Each invoice is a debit (the customer owes more); each credit note is a credit (it reduces what they owe).
• Paid invoices are listed but they don't accrue to the outstanding balance — they're already settled.
• Filter the view by date range and / or a single client.
• Use Print to send it to a physical printer (the sidebar and nav drop out via a print stylesheet), or Download PDF for a landscape branded PDF.
• The four headline numbers — Invoiced · Credited · Paid · Outstanding — are also shown above the table.

7 · Customer statements

A statement is the same data, but cut by a single client and laid out for posting or emailing.

• Open Statements from the tab; pick a client to drill in.
• The statement shows: invoiced and credited totals, the current open balance, and an aging breakdown — Not due / 0–30 / 31–60 / 61–90 / 91+ days.
• Aging is computed from each invoice's due date (or issue date if no due date is set) relative to today in the display timezone.
• Filter by date range to produce a "for the month of …" statement.
• Download PDF renders a portrait branded statement on company letterhead, ready to send.

8 · Clients

Clients are managed per company. When you pick a client on a new invoice, their address and tax ID are copied onto that document — later edits to the client never change historical invoices.

9 · Products & services

• Set a default unit (hour, project, run…) and a unit price.
• Override the VAT rate only if the line is zero-rated or exempt; otherwise leave it blank to inherit the company default.
• Leave the SKU blank — it's auto-generated from the name plus the product ID, e.g. BRAN-0007.

10 · CSV imports

You can bulk-create clients, products, invoices or credit notes from a spreadsheet. Each list page has an Import CSV button that gives you a downloadable template with the right columns.

• Clients and Products imports create independent records.
• Invoices and Credit notes imports use one row per line item — group rows together with the same number and the importer treats them as a single document.
• Rows missing a name (or a product price, or a client name on documents) are skipped — the rest still import.

11 · PDF tips

• Logos render best as PNG or SVG with a transparent background, around 400 px wide.
• Set both brand and accent colors — every PDF (invoice, credit note, ledger, statement) uses a gradient between them on the header band and total badge.
• PDFs always render on white paper regardless of the screen theme.
• The PDF is regenerated on every request — edit a document and refresh.

12 · Localization & time

• The default South African profile is ZAR · en-ZA · 15% VAT · Cape Town · Western Cape. Each company can override its locale.
• Money renders as R 1 234,56 for ZAR and follows the company locale for any other currency.
• Time is anchored to GMT. The server runs in UTC; the UI converts to the display timezone (default Africa/Johannesburg, GMT+2) — visible in the sidebar footer.
• Override the display timezone with the APP_TZ environment variable.

13 · Database

• InvoiceMe runs on SQLite by default — a single file under DATA_DIR/invoiceme.db.
• To use PostgreSQL, either set DATABASE_URL (Railway) or open /setup and paste a connection URL.
• The env var wins. The setup screen writes to DATA_DIR/config.json and only applies when the env var is unset.
• The schema is created and migrated on first connect — no manual step.
• /healthz reports the active source and engine.

14 · Theme

• InvoiceMe ships in dark mode by default. The toggle in the sidebar flips between day and night and remembers the choice locally.
• An inline script applies the saved theme before the first paint, so there's no flash on reload.
• PDFs always render on white paper regardless of the screen theme.