Invoicing & Payments
Quote-to-cash — checkout from rentals, invoice lifecycle, payments, credit notes, deposit/pro-forma invoices, and billing communications.
Overview
Checkout creates a draft invoice with frozen source and tax snapshots. Issue finalises the legal document; standard posting invoices also create financial postings. Recorded payments, effective credits and non-cash write-offs affect the receivable through separate source contracts. PDFs and billing emails use the Document Engine and Notification Engine; issuing an invoice does not confirm that those emails were delivered or that the bank has reconciled payment.
Field-level API contracts — event-sourced records, money serialisation, idempotency, payment and refund payloads, write-off envelopes and financial postings — are in Finance API contracts.
Finance list pages live under the Finance navigation section, gated on invoice permissions (invoices.access, invoices.view); the credit note and payment index pages also require invoices.view.
| Area | Route |
|---|---|
| Invoices index | /invoices |
| Create invoice | /invoices/create |
| Invoice detail | /invoices/{invoice} |
| Edit invoice | /invoices/{invoice}/edit |
| Invoice communications | /invoices/{invoice}/communications |
| Invoice activity | /invoices/{invoice}/activity |
| Invoice plugin tabs | /invoices/{invoice}/tabs/{key} |
| Credit notes | /credit-notes |
| Create credit note | /credit-notes/create |
| Credit note detail | /credit-notes/{creditNote} |
| Payments | /payments |
| Payment detail | /payments/{invoicePayment} |
| Edit payment | /payments/{invoicePayment}/edit |
| Rental checkout tab | /rentals/{rental}/invoices |
| Account invoices tab | /accounts/{account}/invoices |
| Billing run console | /billing-runs |
Bare /finance/credit-notes and /finance/payments URLs redirect with 301 to the canonical routes above.
Financial terminology
| Term | Meaning |
|---|---|
| Draft | Editable invoice before issue. A draft does not create an invoice financial posting. |
| Posting | An immutable, balanced financial record created by an issued document, payment, receipt or allocation. Standard invoices with is_posting true post on issue; deposit and pro-forma documents do not. |
| Settlement | A verified provider receipt, independent of invoice balances. Its gross amount and receipt identity are preserved; it is not proof of a bank payout or reconciled provider fees. |
| Allocation | A portion of a settlement applied to an eligible invoice. The invoice payment represents that allocation, not the receipt's entire gross amount; surplus can remain unapplied. |
| Refund | An operator-attested return of an original payment, recorded as a negative invoice payment. It does not initiate or confirm a provider refund. |
| Write-off | A non-cash receivable adjustment, tracked separately in written_off_total. It does not change cash collected, invoice gross or tax. |
| Reversal | A new adjustment referring to an original write-off and its remaining reversible amount. It does not delete the original write-off or void the invoice. |
| Tax point | The captured date selected by the installed tax-point resolver for effective tax rules. It is distinct from a receipt's payment date. Check your own tax obligations with your adviser. |
| Base currency | The named currency of the stored base amounts. Invoice receivables use their frozen rate/date; cash conversion uses its own receipt or payment date. Never combine different currencies into an unlabelled grand total. |
Draft, posting, settlement and allocation are separate steps. A paid status does not mean the provider payout has been reconciled. Signals does not guess missing historical postings, currencies or conversions.
Write-off rules and tax reporting
Net tax reporting uses frozen signed invoice tax rows and effective issued/applied credit rows, with each document's own recorded tax date and currency partition. It does not multiply the stored credit amounts by effect_sign again. Readiness can refuse unresolved posted voids, missing tax dates, tax-row mismatches, credit scope/provenance conflicts and unrepresentable original monetary precision. The gross invoice_taxes source is refused for CSV export when issued/applied credits exist in the named viewer's permitted warehouses, including retained credits; without those credits it reports gross invoice-only tax. Changing a report date filter does not resolve a refusal; the underlying record must be corrected. See Reporting for the supported sources and export refusals.
Financial postings
Issuing a standard posting invoice (is_posting true) records a balanced financial posting; drafts, deposit requests and pro-forma documents do not post. Credit notes, verified provider receipts, allocations, manual payments and operator-recorded refunds post through their own source contracts, described in Finance API contracts → Financial postings.
Not yet available: provider-initiated refunds and their outcomes, chargebacks, unapplied manual cash, bank reconciliation, and inferred postings for invoices, credits and payments without recorded posting evidence. Deposits are non-posting payment requests: cash stays unapplied until it is allocated to the final posting invoice — see Deposit and pro-forma worked examples.
Write-offs and reversals
In finance settings a settings manager sets a per-currency write-off ceiling in whole minor units (GBP 100 means GBP 1.00; JPY 100 means JPY 100). Zero or no entry disables new write-offs for that currency, but authorised reversals still work. Write-offs are currently dated the current UTC day.
Open Finance → Write-offs on the invoice for post and reversal forms and the permission-gated, paged list of reasons. The REST routes, MCP tools, idempotency rules and response envelope are in Finance API contracts → Write-offs and reversals.
Document references, legal numbers and posting
The Reference column and record header show the document's display reference. By default, an invoice draft has no legal number: Draft invoice #… identifies the editable record, not an issued legal document. A draft credit note similarly displays Draft credit note #… until it becomes effective. Opening a list or record does not allocate a number or create a financial posting.
Issue allocates the invoice's legal number in the same transaction that finalises the document. Immediate credit issue allocates its legal number; a saved draft credit receives its number on Apply. Each uses its own warehouse/document-type sequence. Standard rental and project invoices share their warehouse's standard sequence, but this does not promise gapless numbering.
An explicitly enabled creation-time numbering policy can give a draft its legal number prior. That draft keeps its captured policy and number after a configuration change; Issue or Apply does not allocate a second number when one already exists. A number on a draft does not mean it has been issued or posted. Existing legal numbers are not renumbered.
Legal finalisation and financial posting are separate decisions. Standard posting invoices create financial postings on Issue; deposit and pro-forma documents remain non-posting. An immediate effective credit posts at issue, or a saved draft credit posts on Apply, only when its original invoice was itself posted. A draft has no effective financial posting. PDF generation, email delivery and settlement are separate outcomes.
The early-numbering policy has no announced end date.
Checkout
Checkout generates a draft invoice from a rental's active quote version, copying line items, costs, surcharges, and tax with a penny-reconciliation invariant at fire time. Tax is frozen on the invoice — later rental changes do not alter issued documents.
Checkout is available from:
- The rental Invoices tab in the UI
POST /api/v1/rentals/{id}/invoices— see Invoices API- The Generate invoice button on a rental project's Money register
POST /api/v1/rental_projects/{id}/invoices
For catalogue-backed, non-manual lines, checkout also records the resolved catalogue-item price and rate specification on the invoice line as soft references, so an internal reader can see which rate produced the price without those references ever being treated as a live lookup.
Invoice sources
An invoice has at most one source: a rental, or a rental project, never both. A manual invoice with no source at all remains valid. The source is exposed as rental_id / rental_project_id on the payload, with rentalProject available as an include, and it appears in the UI as:
- a Source column on the invoices index (in the default column set, between Account and Warehouse);
- a Rental Project row under related documents on the invoice detail page.
Rental invoices and project invoices share the same per-warehouse standard-number sequence. Their allocation follows each document's captured numbering policy; sharing a sequence does not guarantee gapless numbers.
Project invoicing
Draft and active rental projects can bill their base-currency project costs — in full, or by partial quantity. Tax and warehouse are taken from the earliest-created live linked rental of the project.
Invoice lines carry a replay-safe snapshot of the source cost (rental_cost_id) and the quantity billed (invoiced_quantity). While a quantity is invoiced, the source cost is locked against destructive edits. Voiding a project invoice, or deleting one while it is still a draft, releases that frozen quantity and unlocks the cost again. The cost link is deliberately soft, so replay tolerates a historical cost having since been removed.
See Rental Projects. Period-end sweeps that include project costs are documented in Billing runs.
Invoice types
| Type | Purpose |
|---|---|
| Standard | Full invoice from the rental (default checkout type) |
| Deposit | Deposit invoice with dedicated partial-invoice tax policy |
| Pro-forma | Pro-forma invoice before final billing |
Pass type in the checkout request body to select deposit or pro-forma generation.
Source states
Checkout validates that the rental is in an allowed source state for invoicing (configured in invoices.source_states). Attempting checkout from a disallowed state returns a validation error.
Idempotency
Financial POST endpoints honour the Idempotency-Key header — see Finance API contracts → Idempotency.
Invoice lifecycle
| Status | Meaning |
|---|---|
| Draft | Editable header; not yet issued and no invoice financial posting |
| Issued | Finalised; payments and credit notes apply |
| Partially paid | Recorded payment exists and a receivable balance remains |
| Paid | Balance-derived invoice state; does not confirm that provider cash reached the bank |
| Overdue | Read-time display for an eligible issued/partially-paid invoice past its due date with outstanding balance; not a stored event status |
| Void | Cancelled issued invoice |
| Credited | Terminal credited state, distinct from recording cash |
The installed default is draft. Tenant labels may change, but custom statuses inherit a built-in status's transition behaviour; renaming a label does not change posting or settlement rules.
Actions
| Action | When | Notes |
|---|---|---|
| Issue | Draft → Issued | Allocates the legal number if absent, retains a number already assigned under the creation-time numbering policy, and locks lines; only admitted posting invoices create financial postings |
| Void | Draft, or an issued non-posting invoice with no recorded payments | Negates billing intent. Invoices with any recorded payment, and posted standard invoices, cannot be voided; issue a credit note or use Cancel (posted standard invoices only) instead. On a project invoice, also releases the invoiced quantity frozen on each source project cost |
| Write-off | Eligible issued receivable under the current permission and per-currency ceiling | Non-cash adjustment; the original invoice and its cash and credit totals are unchanged |
Partial-quantity invoicing lets you bill only part of an order line — useful when equipment is dispatched in stages.
Draft invoices can be edited (header fields) or soft-deleted. Issued invoices are immutable except through payments, credit notes, void, or write-off.
Payments and refunds
Record payments against issued invoices from the invoice detail page or via POST /api/v1/invoices/{id}/payments. The running balance (amount_outstanding) updates across payments and credits.
Refunds record an operator-attested return of prior funded cash via POST /api/v1/invoices/{id}/refunds. Pass original_payment_id when more than one original payment has refundable funds. The selected payment must belong to this invoice and have a recorded posting; the amount cannot exceed its remaining funds. This endpoint does not initiate or confirm a provider refund. Receipt documents can be generated through the Document Engine.
Payments can be listed across invoices with GET /api/v1/payments, or per invoice through the nested GET /api/v1/invoices/{id}/payments route, and in the Finance UI index. See Payments API.
Credit notes
Credit notes mirror invoice tax with negated amounts. Issue full or partial credit from an invoice. Credit-note PDFs render through document templates.
List and show credit notes at /credit-notes or via GET /api/v1/credit_notes. The record page (/credit-notes/{creditNote}) is documented in Credit notes: issued is terminal; draft is the opt-in apply/void path.
PDFs and email
- Invoice PDF —
GET /api/v1/invoices/{id}/pdfor download from the UI - Credit note PDF — generated via the Document Engine
- Billing email —
POST /api/v1/invoices/{id}/emaildispatches invoice, receipt, or statement communications through merge-field templates
Human-readable download filenames are set on every document download path.
Invoice margin
When the viewer has costs.view, invoice detail shows real margin figures computed from line costs. Users without cost visibility see totals without cost breakdown — cost fields are gated, not whole resources.
Using it in the app
Finance screens live under the Finance section of the main sidebar and header mega-menu. The whole Finance block — Invoices, Credit Notes, and Payments — is visible only when the user holds invoices.access. Individual pages then check finer-grained invoice permissions (invoices.view, invoices.create, and so on).
| Screen | Route | Mount permission |
|---|---|---|
| Invoices index | /invoices |
invoices.access |
| Credit notes index | /credit-notes |
invoices.view |
| Payments index | /payments |
invoices.view |
| Invoice detail | /invoices/{invoice} |
view policy on invoice |
| Invoice communications | /invoices/{invoice}/communications |
view policy on invoice |
| Rental Invoices tab | /rentals/{rental}/invoices |
invoices.view |
| Account Invoices tab | /accounts/{account}/invoices |
invoices.view |
Finance index pages
All three Finance list pages use the shared data table with column toggles, export, column filters, and a live filter selector (Default / System / Shared / My Live filters). Saved views drive columns, filters, and sort — the same machinery as other index pages.
Invoices (/invoices) shows status chips across the top (All, Draft, Issued, Paid, Overdue, and so on) with live counts. Columns include Reference, Type, Status, Account, Source (the rental or rental project the invoice was raised from, blank for a manual invoice), Warehouse, Total, Outstanding, and Issued. Reference shows the draft identifier or existing legal number, as described above. Overdue invoices carry a red Overdue badge in the Status column. The toolbar offers New Draft when the user has invoices.create.
The New Draft Invoice form groups Customer (Account and Warehouse) and Pricing (tax basis and Reference); expand More details for Notes. It lets you choose Tax inclusive, initially using the finance default. The choice is fixed when the invoice is created and shown read-only when editing its header. Rental-derived invoices keep their rental's tax basis.
Credit Notes (/credit-notes) matches the same pattern with status chips and columns for Reference, Invoice, Account, Issued, Total, and Status. Reference can be a draft identifier or an existing legal number. The header mega-menu labels this area Refunds & adjustments.
Payments (/payments) lists every payment and refund recorded against invoices. Columns include Reference, Invoice, Account, Method, Paid date, Amount, and Type — refunds appear with an amber Refund badge.
Invoice detail — quote to cash
Open any invoice from the index, a rental, or an account tab. The page header shows its display reference (draft identifier or existing legal number), status badge (colour-coded — red for overdue), type badge, and deposit/pro-forma chips when applicable. The status and document type determine its lifecycle and posting eligibility; an existing number alone does not.
Header actions are policy-gated and appear only when legal for the current status:
| Action | Permission | When shown |
|---|---|---|
| Edit | invoices.edit |
Draft only |
| Issue | invoices.issue |
Draft |
| Record Payment | payments.record |
Issued with balance |
| Credit Note | invoices.credit |
Issued with creditable balance |
| Download PDF | — | Non-draft |
| — | Non-draft (dispatches billing communication) | |
| Void | invoices.void |
Issued per policy |
| Delete | invoices.delete |
Draft only |
The shared record navigation appears above and below the content. Overview shows headlines and briefing above the line items and their totals, with one counterparty sidebar. Cost columns require costs.view.
| Navigation | Page |
|---|---|
| Finance → Totals & margin | /invoices/{invoice}/totals — totals and permitted margin figures |
| Finance → Reconciliation | /invoices/{invoice}/reconciliation — reconciliation evidence |
| Finance → Write-offs | /invoices/{invoice}/write-offs — shown when you can view write-offs |
| More → Details | /invoices/{invoice}/details — supporting details and related records |
| More → History | /invoices/{invoice}/history — audit history |
| Docs | Documents and Communications |
A group containing just one visible page opens as a direct link.
The Communications tab lists billing emails and related customer communications for this invoice (channel, status, title, timeline) using the same log table component as the admin Communication Log.
Credit notes from invoice show: click Credit Note to open a modal. Choose full credit or partial credit with per-line quantities capped at the remaining creditable amount. Notes are optional. Check Save as draft to create a draft (IssueCreditNote with draft: true) — the invoice balance does not move until Apply on the credit-note record. Unchecked, issue remains immediate-effect and terminal. Issued and draft notes appear on /credit-notes and the invoice’s More → Details page.
Full credit reverses all remaining uncredited invoice lines and their original tax, regardless of payments already received. For a £360 invoice with £100 paid, full credit is £360 and the invoice's amount_outstanding becomes -£100: customer credit that can be refunded through the refund endpoint. Full credit does not itself refund or erase the payment. The API uses the same rule when lines is omitted or null.
The invoice Overview has an identity band, headline cards that drill ?register=recon|alloc|life, a signed-variance bar on reconciliation, four briefing verdicts, and tabs for documents, activities, and communications. Plugins can add further tabs.
Payments: Record Payment opens a modal pre-filled with the outstanding balance. Enter amount, method (bank transfer, card, cash, and so on), and an optional reference. Each payment has its own record page at /payments/{invoicePayment} — one amount against this invoice, no remittance split. See Payments.
PDF download uses an existing generated document when available; otherwise it queues generation and prompts you to retry shortly. Email triggers the invoice billing communication through the notification engine.
Rental Invoices tab
On a rental, open the Invoices tab (/rentals/{rental}/invoices, badge = invoice count). The tab requires invoices.view; generation buttons require invoices.create plus an allowed rental source state.
| Button | Creates |
|---|---|
| Invoice | Standard invoice from the active quote (hidden when fully invoiced) |
| Generate Deposit | Deposit invoice using the default deposit percentage setting |
| Generate Pro-forma | Pro-forma invoice |
When every order line has been fully invoiced, the primary Invoice button is replaced by a Fully invoiced label — no further standard invoices can be generated from the UI. Progressive partial-quantity checkout is supported by the API (lines on the checkout payload) but is not exposed as a line-selection UI on this tab yet.
Successful generation redirects to the new invoice's detail page.
Account Invoices tab and statement
The account Invoices tab (/accounts/{account}/invoices) shows an Outstanding Balance summary panel and a table of all invoices for that account. Users with accounts.view can pick a Statement warehouse and click Email Statement to dispatch an account statement communication (SendAccountStatement).
Balances in more than one currency
The statement, the statement email and the account Outstanding Balance panel never add money of different currencies. Each outstanding invoice keeps its own currency and its recorded precision (for example JPY with no decimals and KWD with three).
- One currency.
statement.balance_statusiscomplete.statement.closing_balanceholds the balance andstatement.currency_codeholds its currency. The seeded template prints the currency code next to every amount. The documentcurrency_codeis the statement currency. - Two or more currencies.
statement.balance_statusismultiple_currencies.balanceshas one entry for each currency.statement.opening_balance,statement.closing_balanceandstatement.balance_notehold the text "Multiple currencies: see the balance for each currency", andstatement.currency_codeis null. - Unresolved money. An invoice with a blank or unknown currency, or with malformed recorded units, is not added to any balance, and its currency is never taken from the account.
statement.balance_statusisincomplete, and the three balance fields hold "Incomplete: one or more invoices have unresolved money". The invoice line shows "Unresolved: invoice currency unknown" or "Unresolved: invoice money precision invalid", andunresolved_invoiceslists the invoice with a reason code (invoice_currency_missing,invoice_currency_invalidorinvoice_money_units_invalid).
For the last two states, the document currency_code is the account currency, because the column cannot be empty. That value does not describe the statement money: use statement.balance_status and balances.
A custom statement template or API reader that passes statement.opening_balance or statement.closing_balance to number_format or to a currency format must first check that statement.balance_status is complete, because in the other states these fields hold text.
The amounts in the statement data are bare decimal numbers, with no currency. A custom statement template must print the currency next to each amount: statement.currency_code next to the single balance, balance.currency_code next to each balance in balances, and invoice.currency_code next to each invoice amount. A stored custom template that does not do this prints numbers with no currency. The seeded template does it.
Billing emails (invoice, receipt, credit note and statement) print money in the currency of the document. A money merge field holds integer minor units only when its currency is the company base currency at the ISO precision. Otherwise it holds the amount already formatted in its own currency and precision (for example $12.50, ¥12,500), and the currency filter prints it unchanged. When the statement email has two or more currencies, statement.closing_balance lists each balance with its ISO code (JPY 12,500; KWD 10.005), because several currencies can share one symbol. statement.closing_balances[] holds currency_code, decimal_places and the formatted display for each currency; it holds no raw amount. Money with an unresolved currency or precision shows a note instead of an amount. Seeded statement templates use the per-currency layout; customized templates retain their body.
Permissions summary
| Permission | UI effect |
|---|---|
invoices.access |
Finance nav links (Invoices, Credit Notes, Payments) |
invoices.view |
View lists, rental/account tabs, invoice detail |
invoices.create |
New Draft, rental generate buttons |
invoices.edit |
Edit draft header |
invoices.issue |
Issue action |
invoices.void |
Void action |
invoices.delete |
Delete draft |
invoices.credit |
Credit Note modal |
invoices.write-off |
Write-off/reversal forms and paged adjustment reasons, subject to invoice warehouse access |
payments.record |
Record Payment modal |
costs.view |
Invoice margin column and summary |
Recording refunds is not yet exposed in the invoice detail UI — use the Payments API for operator-recorded refunds. Write-offs and reversals are available on the invoice page and through the API (see above).
Finance guides and API contracts
Every finance action checks the caller's current permissions and warehouse access. Seeing a route or a dashboard does not grant access to it.
Guides
| Task | Guide | Notes |
|---|---|---|
| Review, issue and undo a billing run | Running a billing run and Billing runs | Undo applies only to eligible non-posting documents. Cancelling a posted invoice is a separate action. |
| Payments, allocations and receipts | Payments | A negative payment does not confirm a provider refund. |
| Invoices, postings and write-offs | Invoicing & Payments (this page) | Voiding an eligible non-posting document differs from cancelling a posted invoice. |
Settlement queue and finance operations
The staff settlement queue at /payments/settlements is described in Payments → Settlement operator queue. The read-only Finance tab under Admin → System → Integrity is described in Finance operations → Finance operations dashboard. Failed billing-run items cannot be retried yet — see Billing runs.
API and MCP
Payment and refund payloads, settlement allocation over MCP and posted-invoice cancellation are described in Finance API contracts → Recording payments and refunds.
Translations
The settlement queue and finance operations labels (Settlement queue, Finance operations, Unavailable) are available in all seven installed language packs (en-srf, de, es, fr, it, pt, zh). Do not use a translated label as an action identifier or error code.
Additional form guidance
Payment and credit-note commands validate their configured custom fields before recording events. The invoice dialogs place those fields above the action buttons and omit the section when no fields are configured.
Related documentation
-
Credit notes — record page, draft→apply, terminal issued
-
Payments — single-invoice payment record
-
Tax & Compliance — zone-aware tax frozen at checkout
-
Documents & Templates — PDF rendering and numbering
-
Notifications & Comms — billing email delivery
-
Billing runs — period-end batch invoicing
-
Invoices API — REST surface and abilities
-
Finance API contracts — payloads, postings and ledger contracts
Margin cost coverage
For users with cost visibility, the invoice totals rail shows the known cost-line count, lines without a cost basis, and original unattributed cost sources. Incomplete or excluded cost remains Unknown, and a partial or unavailable margin cannot display as complete. Missing issue-time cost data shows unavailable coverage rather than zero cost.
Unattributed source amounts retain their own currency and integer minor units. They appear before invoice allocation, alongside the reader's allocation ratio; the display does not add source currencies or invent a converted total. Issued invoices use their original issue-time cost data. Cost-restricted users see none of this coverage, and the margin reader is not invoked for them.