Invoices

An invoice is a bill against a job. A job can carry one — billed at the end — or several, billed in stages as the work goes. Worksite stores what an invoice is for as well as its number and its amount, so a bill from six months ago still explains itself when a customer disputes it.

Where this stands in v1: the invoice model, numbering, and frozen-derivation rule are all live. What you cannot do yet from a screen is generate or view an invoice — that surface ships in a follow-up. Today, invoices exist as a record shape and are ready for the generation UI to attach.

What an invoice records

Every invoice on a job carries:

The job it bills against — every invoice belongs to exactly one job.
The master bid it settles. The bid the customer signed that authorizes the work. An invoice with no master bid is a rare case (a hand-recorded historical bill); one with a master bid is the norm.
The change orders included. If the job's total grew after signing because change orders were approved, each one that's covered by this invoice is named on the record.
The deposits deducted. A shop typically bills gross, then subtracts the deposit already collected. The deposit rows this invoice deducts are recorded here too.
The frozen amount. The number sent to the customer, stored as entered. See below on why it doesn't move.
The date it was issued. When the shop asserts the invoice was sent.

Why the amount is "frozen"

Worksite's rule for anything the customer has seen is: once it's out in the world, it doesn't change under them. A bid that was sent keeps its price ([[ADR-0002]] in the code). Invoices extend that one step.

Practically: if you issue Invoice #1 for $10,000 today, and next week you sign a change order that adds $500 to the job, Invoice #1 still reads $10,000. The change order changes future billing; it does not edit past bills. A customer looking at their file a year later sees exactly what they were sent.

How invoices are numbered

Every invoice on a job takes its own place in a series:

J-1042-INV1 — first invoice on Job 1042
J-1042-INV2 — second invoice on the same job

The INV prefix keeps invoices visually distinct from bids and change orders on the same job (which are J-1042-v1, J-1042-CO1, and so on).

Numbers are not reused. If an invoice is deleted, its number is gone; the next invoice on that job takes the next-higher number, not the deleted one's. A number quoted to a customer must never point at two different bills.

Two questions the system can answer

The system now supports two "give me the full paper trail" queries that the follow-up UI will hang on:

All documents on a job — every bid, change order, and invoice for a single job, in one list.
All documents for a customer — every bid, change order, and invoice across all their jobs.

Both come back tenant-scoped (a shop only sees its own work) and newest first within each kind. Useful when a customer calls with a question and you want the whole thread on one screen.

What's not in v1 yet

The invoice concept is real; the surfaces around it are not. Called out so you don't hunt for controls that aren't there:

No screen creates invoices yet. No "Bill this job" button. When the UI lands, it will use the model already shipped.
No invoice PDF. No customer-facing invoice document is generated today.
No payment tracking on invoices. Money coming in still lives as a Deposit row on the job — Worksite records what a person asserts about money and gates on it; ledger-shape reconciliation is out of scope for v1 per [[ADR-0059]].
No automatic invoice generation from a job's state. When Stage 6 work completes, no invoice is drawn up unless a person does so.

[[Building a bid|Bids]] — the master bid that most invoices settle
[[Approvals, deposits, and pre-lien|Deposits]] — the money-in side that invoices deduct from the gross
[[After the sale — provisioning through closeout|Stages 4–7]] — the job phases that produce the work an invoice bills for