Invoicing a time box
What this page is — How a finished (or running) stage 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 · 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. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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_timeboxand the time box's id, so a Books user can see where an invoice came from.
7. 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.
8. 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 |