Invoicing
What this page is — How a finished (or running) stage — or an achieved contract line (a priced milestone) — becomes an invoice in Orbit Books, and the bills that go to the contractors who did the work. What it is for — Billing what was actually delivered, from the same place the work was planned, without retyping it into an invoice. The problem it solves — The plan already knows what each task is worth and how far it has got. Without this, somebody reads that off the board and types it into Books, which is where the number goes wrong — and nothing remembers what has already been billed.
Route: Planning → Live → a committed time box → Raise invoice · Planning → Value → a priced line → Raise invoice · Permissions: Raise invoice (task.planning.invoice) and the Books permission to create an invoice
Module: Planning · Needs: the project linked to a Books entity, a customer on the project, and money turned on
1. Why you would use it
- A stage is finished and the customer should be billed for exactly the work in it — no retyping task values into Books.
- Work is billed as it runs (running or RA bills): each bill carries only the progress made since the last one.
- The contract pays on milestones — "wood work complete", with 5 % held back until handover — and the invoice has to match the line, not the tasks' sum.
- Contractors are paid for their part of the same work, and their bills should be drafted from the same lines.
2. What has to be true first
| Check | Why | Where to fix it |
|---|---|---|
| The project puts a value on its tasks | There is nothing to bill otherwise | Settings → Money |
| The project is linked to a Books entity | An invoice belongs to a legal entity | Books → Entities → Projects |
| A customer is set for the project | An invoice is addressed to somebody | Settings → Money → Customer for invoices |
| The project's currency matches the entity's | Planning does not convert silently | Settings → Money, or the entity's base currency |
| You may create invoices in Books | Billing is a Books action | Your role's Books permissions |
| There is something to bill | — | Finish some work, or pick the other mode |
Each of these appears in the drawer with the reason, before anything is created. Three more things are shown as warnings and do not stop you: the time box is not marked Completed, some of its tasks are not done, and some tasks carry no value.
3. The two ways to bill
| Mode | What goes on the invoice |
|---|---|
| On completion | Every done task with value left to bill, in full |
| Progress | Every valued task: its value × how far it has got, minus what has already been billed |
Progress is read from the task's remaining hours against its estimate — the same figure the board's Progress field shows.
Nothing is ever billed twice. Each task remembers what has gone out (an invoice line records the progress it covered). Raising the same invoice again bills nothing; voiding or cancelling the document in Books makes that value billable again.
Work that goes backwards bills nothing. If a task was billed to 60% and now reads 30%, the line is dropped and the drawer says so. Planning never raises a credit note on its own — that is a decision for a person, in Books.
Two small floors keep rounding noise off a document: an amount under half a cent, and progress that has moved by less than half a point.
4. Billing a contract line
A priced milestone is billed from the Value tab — the line card's Raise invoice, or the row in the Payment schedule. The drawer is the same, with the line's own figures on top (Line · Invoiced so far · Left to bill) and three more things:
| How to bill | Follows the line's billing trigger — On completion (its done contributing tasks), Progress (what they have earned since the last bill), or An amount: a sum you type, spread over the contributing tasks in proportion to their value so each task still remembers what went out. An amount larger than what is left of the line is refused. |
| Retention | A line with a retention share goes out net: every line is reduced by the share, the withheld sum shows as its own row, and the document asks for the rest. The withheld sum waits on the line (Retention held) until Release the retention held raises the separate invoice that frees it — one line, dated the day it is raised, no task ledger. |
| Due date | The document is due on its date plus the line's payment terms (or the project's default terms); Planning passes it to Books. |
Two rules hold whatever the mode: a line never bills more than what is left of it (the tasks may have earned more — the invoice stops at the line and says so), and a task billed through its stage is not billed again through its milestone — both write the same ledger. Mark this milestone achieved sets the milestone to Completed once the document is raised.
Warnings on a line: its contributing tasks are not all done (not achieved yet), its tasks do not add up to the line (allocation variance), retention is withheld, or the earned amount was capped at the line.
5. Raising it
Open the project's Live tab and pick a committed stage. Its Value card shows what the stage is worth, how much of it is done, and how much has been invoiced and paid — the bar shows the work finished and, inside it, the part already billed.
Raise invoice opens the drawer:
- Before it goes out — the checks above, blocks first.
- How to bill — the mode (the project's own is pre-selected), and three ticks: Issue it now (otherwise it stays a draft), Mark this stage completed, Also draft the contractor bills.
- What goes on the invoice — a line per task with its description and amount, and the total.
- Contractor bills to draft — see below.
- Already raised — what Planning has billed for this box before, with its live Books status, total and balance.
The button reads Create draft or Issue, with the amount.
The invoice is dated today, not the stage's planned end date: a stage is often finished later than it was planned to be, and the bill is dated when it is raised. The planned window is recorded on the document.
6. Field reference — the drawer
| Field | What you provide | Notes |
|---|---|---|
| How to bill | On completion, Progress, or — on a contract line — An amount | Pre-set from the project's invoice mode (a stage) or the line's billing trigger (a milestone) |
| Amount to bill | A sum, contract lines in An amount mode only | Blank = whatever is left of the line; more than that is refused |
| Issue it now | Tick to issue instead of leaving a draft | A draft is not owed; the Payment schedule counts it separately |
| Mark this stage completed / milestone achieved | Tick to close it once the document is raised | Sets the time box or milestone to Completed |
| Also draft the contractor bills | Tick to draft one bill per contractor | Not offered for an amount or a retention release |
| Release the retention held instead | Contract lines holding retention | Raises one line for everything held; the earlier documents are marked released |
7. Contractor bills
With Also draft the contractor bills ticked, the lines you are billing the client for are grouped by the contractor their task is planned on, and each group becomes a draft bill from that contractor, addressed to its vendor in Books. Tasks on your own people carry no bill — that is your own cost, not a supplier's.
A bill is always a draft: it is confirmed by the vendor or by whoever handles your payables, never by the planner.
A contractor with no CRM vendor behind it cannot be billed — it is listed as skipped, and the customer invoice still goes out.
8. Worked example
The Kitchen stage of Anand's flat is worth ₹4.2L: ₹3.6L of it is done, ₹2.4L was billed last month as a running bill. The studio finishes the carcass work and raises the next bill: Progress, tick Also draft the contractor bills. The drawer warns that two tasks are still open — fine, progress billing expects that — and lists five lines totalling ₹1.2L, each saying the progress it covers ("progress 60% → 100%"). Alongside it, a draft bill of ₹90,000 from Sharma Carpentry. They tick Issue it now, and the invoice goes out numbered from Books. The Value card then reads ₹4.2L planned · ₹3.6L done · ₹3.6L invoiced.
9. The admin contract
- Raise invoice needs
task.planning.invoice— separate from Manage planning on purpose: planning the work and billing for it are different jobs. - It is not enough on its own. Creating the document also needs the Books permission, checked by Books; the drawer says so up front rather than failing halfway.
- Planning keeps its own record of what it billed (which invoice, which task, how much, to what progress). That is what makes "never bill twice" and "a void makes it billable again" work; Books stays the book of record for the document itself.
- Documents raised here carry a source of
planning_timebox(a stage) orplanning_milestone(a contract line) and the id of what was billed plus Planning's own record, so a Books user can see where an invoice came from and a stage or line can be billed more than once (running bills, a retention release). - Retention is Planning's: the Books document is net, Planning records the withheld sum and which later invoice released it. The task ledger stays gross, so Invoiced on the Value tab counts what the customer owes for the work, not what the document asked for.
10. Don't confuse this with…
- Settings → Money — where the value mode, currency and customer are set.
- Orbit Books → Invoices — where the document lives once raised: numbering, tax, issuing, payments, credit notes.
- Project → Billing — the effort-based billing analytics; unrelated to what a task is worth here.
11. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| No Raise invoice button | You lack task.planning.invoice, or money is off for the project | Ask for the permission; turn on Money |
| "This project is not linked to a Books entity" | No books_entity_projects row | Books → Entities → the entity → Projects |
| "You cannot create invoices in Books" | You hold the planning permission but not the Books one | Ask for the Books invoice-create permission |
| "Nothing to bill" | Depends: no task carries a value, everything is already billed, or nothing is done yet — the message says which | Value the tasks, finish some work, or switch to Progress |
| The same stage billed nothing the second time | Every task remembers what has gone out | Expected. Void the earlier document in Books to bill it again |
| A contractor was skipped | The contractor has no CRM vendor behind it | Link it in Planning → Define → Contractors, from a project vendor |
| The invoice is dated today, not the stage's end | Deliberate — the bill is dated when it is raised | Change the date in Books if your process needs it |
| "This milestone has no chargeable amount" | The line is not priced | Put the amount on it in the Roadmap's Milestone drawer |
| "More than what is left of the line" | The typed amount exceeds line − invoiced | Type less; the placeholder shows what is left |
| The invoice asks for less than the lines add up to | Retention | Expected — the difference shows under Retention held and is released by its own invoice |
| "No retention is held on this line" | Nothing withheld, or already released | Nothing to do |