Invoices & Billing

1In one sentence#

The Invoice module is LumosCRM's billing engine — it produces proposals, estimates, invoices, and credit notes; calculates line-level tax and discounts in any currency; issues a polished, EU-compliant document; shares a secure pay-online link with the client; and tracks payments and refunds end-to-end, with everything locked down and audited once issued.

It's not just an invoice list — it's the full quote-to-cash path: pitch a price, get it approved, bill it, collect it.

2Who it's for#

3The core idea: one engine, four document types#

A single, consistent record powers four kinds of billing document, each with its own lifecycle:

   PROPOSAL  ──accepted──▶  ESTIMATE  ──approved──▶  INVOICE  ──paid──▶  ( + CREDIT NOTE )
   (a pitch)               (a firm quote)          (a bill)            (a refund/adjustment)

   every document shares: line items · tax · discounts · totals · currency
                          recipients (bill-to) · attachments · audit

You can convert a proposal into an estimate and an estimate into an invoice — carrying the detail forward — and duplicate any document to start a similar one. This means the same trusted calculation and presentation engine serves the whole sales-to-billing journey.

4Capabilities at a glance#

5Lifecycles & states#

Because the engine serves four document types, each has its own status path:

Separately, every billable document tracks a payment status: unpaid · partially paid · paid · overpaid · refunded · written off · not applicable.

Money is stored in minor units (cents) so totals are always exact, and a GDPR lawful basis and retention date are recorded for compliance. Voided documents drop out of normal views automatically.

Note for marketing: statuses, payment methods, and number sequences are configurable; the calculation and locking rules are fixed.

6The issue-and-lock model — trustworthy documents#

LumosCRM treats an issued billing document as a legal artefact:

• While a document is a draft, it's fully editable — add lines, change tax, adjust discounts.
• Issuing it (a deliberate action) stamps the issuer and time and locks the financial content. From then on, the numbers can't be quietly changed.
• After issue, only limited fields remain editable — for example, client-facing notes stay editable until the invoice is fully paid; internal notes can always be updated.
• To correct an issued document you void it (with a reason) or raise a credit note — never silent edits.

This protects both the agency and the client: what was sent is what stays on record.

7Tax & discounts — done properly#

• Tax is driven by a managed tax-rate catalogue (maintained in Settings → Finance). When you add a rate to a line, the system snapshots it and computes the tax on the line's subtotal — so historical invoices keep the rate they were issued with even if the catalogue changes later. Reverse-charge is supported for EU cross-border billing.
• Discounts work at both the line level and the whole-invoice level, as either a percentage or a fixed amount. Percentage discounts are computed against the live base, so the maths always reconciles.
• The totals — subtotal, discount total, tax total, and grand total — are recalculated automatically whenever lines change, with a rounding adjustment so the figures always add up.

8Screen-by-screen walkthrough#

8.1The invoice list (index)#

A filterable list with currency-scoped KPIs (mixing currencies would be meaningless, so the figures scope to a chosen currency): outstanding, overdue, paid, and year-to-date. Search and filter by status, document type, client, and date; status and payment badges per row; a New button in the header.

8.2Creating & editing a document#

A focused builder with a header-actions ribbon and a completion ring. The standout is the add-line drawer — a unified staging area where you pull in items from several sources, set quantities and prices, apply inline tax, and step straight to a live preview of the finished document. The preview renders an EU-style invoice document so you see exactly what the client will get. A save-then-issue flow lets you save the draft and issue it in one confident motion.

8.3The document workspace (show page)#

A header with the document number, client, status, and a status stepper showing where it is in its lifecycle. Action buttons (gated by the lock state and permissions): Issue, Send, Convert, Duplicate, Record payment, Void, and Share public link. Tabbed content (each tab permission-gated), loaded on demand:

8.4The public invoice view (no login)#

Each document can be shared via a secure, unguessable link. The client opens a clean, branded page showing only a sanitized, whitelisted version of the document — no internal notes, no encrypted fields, nothing private — and can pay online by card. The link can be rotated or expired. Card settlement is confirmed by a webhook (the source of truth), not by the browser redirect, so a payment is only ever marked paid when the money has actually moved.

9Payments & refunds#

Payments can be recorded manually (e.g. a bank transfer) or collected online via Stripe Checkout from the public link. The module tracks partial payments, overpayment, and refunds, keeps a running amount paid / amount due, and lets staff refund a payment. Invoice payment state updates are event-driven, keeping billing cleanly decoupled from the payment provider (see the Payments module).

10Security & access control#

• Granular permissions per section: invoices.record.* for the document and its domain operations (issue, send, void, convert, payments), plus invoices.items.*, invoices.financial.* (discounts), invoices.recipients.*, and invoices.attachments.*.
• Per-user record scoping (self-scoping): self-scoped staff see only the documents they created/own; broader roles see all.
• Encryption: void reasons, billing tax IDs, payment instructions, and internal notes are encrypted at rest.
• Public link safety: unguessable, expirable token; sanitized payload; webhook-confirmed payment.
• Compliance: GDPR lawful basis and retention dates on every document; locked, immutable issued records.

11Search & integration#

• Global search (⌘K) and entity pickers surface invoices across the CRM.
• Cross-module ties: a document links to a client (and shows on their Financial tab, with the client's preferred currency pre-selected), and can be tied to a request or event. Attachments promote into the Document Vault, and payments flow through the Payments module.

12Use cases & scenarios#

Use case A — Pitch to payment#

A manager sends a client a proposal for a yacht week. The client accepts; the manager converts it to an estimate, then to an invoice, carrying the lines forward. They issue it, share the public link, and the client pays by card — the invoice flips to paid when the webhook confirms.

Use case B — Getting the tax right#

Billing a French client from a Monaco entity, finance applies the correct VAT rate from the catalogue and ticks reverse charge where it applies. The issued invoice keeps that exact rate forever, even if the catalogue is updated next quarter.

Use case C — Fixing a mistake cleanly#

An issued invoice had the wrong amount. Rather than editing it, finance voids it with a reason and issues a corrected one — or raises a credit note — leaving a clean, auditable trail.

Use case D — Chasing the balance#

The list's currency-scoped KPIs show €40k outstanding and €8k overdue. Finance filters to overdue invoices and follows up, watching partial payments land and the balance fall.

Use case E — A clean record for every document#

Months later, an auditor asks who issued an invoice, when it was sent, when the client viewed it, and how it was paid. The History tab has it all — status, financial, and access logs — unchangeable.

13Permissions reference (simplified)#

The public view and pay routes are unauthenticated (secured by the token). Roles are assembled from these permissions in the RBAC module.

14Glossary#

15Platform foundations (built into the data model)#

A few capabilities are modeled and partly wired, worth knowing for the roadmap story:

• Document conversions & revisions are fully modeled (proposal→estimate→invoice, credit notes, and revisions via a parent link) — the conversion and duplicate actions are wired.
• Configurable number sequences let an agency define its own invoice numbering.
• Multi-currency reporting stores an exchange rate to a base currency on every document for consolidated reporting.

Recurring/subscription billing is not part of this module today; the data model is structured to allow it later.

This document describes the Invoice module as currently built. Statuses, payment methods, tax rates, and number sequences are configurable in Settings. Money is stored in minor units; the calculation and issue-lock rules are fixed business logic.