--- description: "A ticket traces work to a client. But rollout projects and migrations live in Projects — and until now, project work that skipped tickets had no path to an…" --- # How to bill project work — contracts, milestones, fees > **Audience:** admin (billing setup and runs are an admin + bookkeeper > surface). Project leads benefit from knowing where their phase money > stands. Clients see only issued invoices. A ticket traces work to a client. But rollout projects and migrations live in Projects — and until now, project work that skipped tickets had no path to an invoice. This lesson covers the four seams that close that gap: link a project to the contract it bills through, set a phase budget and watch its burn, release a milestone (or a fixed-fee phase) into the invoice run, and log project time without a ticket detour. The seeded demo org already carries a working example: the Acme Network Refresh project bills through contract CT-1001, its completed Discovery phase holds a staged $1,200 release, and its Implementation phase burns against a $1,500 budget. ## 1. Link the project to its contract A linked project bills through its contract: the contract's rate card prices approved phase time, and the contract's invoice runs carry the project's releases. Open a project and set **Billing contract** (or `PATCH /api/projects/{id}` with `billing_contract_id`). One rule applies: the contract must belong to the same client as the project. An Acme project cannot bill through a Northwind agreement, and the API refuses the link rather than silently mis-billing someone. Leaving the field empty keeps the project non-billable — internal work, fixed-price retainers you handle outside the system, anything that should never appear on an invoice run. The link prices nothing by itself. Money moves when a release is staged or approved time lands. ## 2. Set a phase budget and read the burn For time-and-materials phases, set the contracted budget on the phase: **Create phase** or **Edit phase**, then `budget_minor` + `budget_currency` (or `fee_minor` + `fee_currency` for a fixed-fee phase, below). The budget is the denominator for the burn read model. `GET /api/projects/{id}/phase-burn` returns one row per phase: - `consumed_minutes` and `consumed_minor` — approved, billable entries scoped to the phase, priced at the linked contract's rate card. - `budget_minor` — what the client agreed the phase costs. - `alert` — `none` under 80%, `warn` at 80% or more, `over` at 100%. A phase with no budget always reports `none`, on purpose: no budget is not a zero budget, and reporting `over` on a never-agreed number would invent a commitment nobody made. When a phase crosses into `warn`, the honest responses are a change order, a client conversation, or an accepted loss — the number tells you which conversation to have. ## 3. Release milestones into the run A completed milestone phase with an amount (the existing `milestone_amount_minor` on the phase) doesn't wait for anyone to remember it. Completion stages a **release** — one ledger row carrying the phase's name and amount, dated the day it completed. You can inspect the ledger any time at `GET /api/projects/{id}/billing-releases`. The first invoice run on the linked contract whose window covers the release date bills it as its own `project_release` line and flips the ledger row to `billed` with the invoice reference. A pending release bills on the next run. It never bills twice, because the run flips the ledger row in the same transaction that issues the invoice — a replayed completion event lands on an already-`billed` row and stays inert. Corrections have one door: cancel a `pending` release (`POST .../billing-releases/{id}/cancel`) before it bills. A `billed` release is immutable, like every issued invoice — fix it through a credit note. ## 4. Release a fixed-fee phase Not every phase is a milestone. A phase with `fee_minor` + `fee_currency` in its billing record releases that fee on completion, same ledger, same run behavior, same one-time guarantee. Milestone phases keep using their milestone amount. The fixed fee is for the phase that just costs what it costs whenever it's done. ## 5. Log project time without a ticket Time entries normally require a ticket. Project-scoped entries relax exactly that: `POST /api/time-entries` with `phase_id` instead of `ticket_id` logs the entry straight onto a phase. Exactly one parent is allowed — an entry belongs to a ticket or to a phase, never both, never neither, and both the API and the database check it. Approval works the same queue you already run. Project entries appear alongside ticket entries and bill the same way. Billing consumes them through the phase (the burn read model above), so a project entry pays without anyone spinning up a ticket to carry it. ## What this does not do No per-phase rate cards: phases price through the linked contract's card, full stop. No automatic phase completion on burn-out: a budget exhausting is a documented, alerted fact, and a phase completing is a human decision. And no currency mixing across a run — a project whose releases are in a different currency than its contract bills in a separate run window, same as any other mixed-currency situation.