SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

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.

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}/pdf or download from the UI
  • Credit note PDF — generated via the Document Engine
  • Billing email — POST /api/v1/invoices/{id}/email dispatches 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
Email — 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_status is complete. statement.closing_balance holds the balance and statement.currency_code holds its currency. The seeded template prints the currency code next to every amount. The document currency_code is the statement currency.
  • Two or more currencies. statement.balance_status is multiple_currencies. balances has one entry for each currency. statement.opening_balance, statement.closing_balance and statement.balance_note hold the text "Multiple currencies: see the balance for each currency", and statement.currency_code is 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_status is incomplete, 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", and unresolved_invoices lists the invoice with a reason code (invoice_currency_missing, invoice_currency_invalid or invoice_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.

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.