Books · Invoices

Invoices execution

Read the exact action guide for prerequisites, identifier discovery, supported input, effects, captured successful and refused responses, verification and recovery. Synthetic fixture results do not authorize a live mutation or establish a provider outcome.

• Preview invoice email: Render the current branded invoice email with effective From and Reply-To and optional custom message. No event, share, delivery or invoice mutation is created.
• List invoices: List invoices newest first. Filter by status, contact or issue date, search the number, reference and notes, and sort by issue date, due date, number, total or status. The response carries the outstanding total for the filtered set.
• Create an invoice: Save a draft invoice for a customer. Totals are computed from quantity, unit amount, line discount and tax, never taken from document totals, so the document always foots. Approval allocates the permanent invoice number.
• Get an invoice: Read one invoice with its lines and the payments against it.
• Copy an invoice: Create a new independent draft with the customer, dates, currency, reference, notes, tax treatment and line items from an existing invoice. Number, approval, delivery, payment, write-off, public-page and checkout state are not copied.
• Update an invoice: Change a draft invoice. Sending lines replaces them all and recomputes discounts and totals. Financial details are locked after approval.
• Approve an invoice: Lock a draft invoice and allocate its next gap-free workspace number. When enabled in workspace settings, idempotently create its customer page and Topolo Pay payment link. Repeating the action retries only missing automation without consuming another number.
• Send an invoice email: Send an approved invoice to an external email address through Topolo Notify, with the branded PDF attached and a secure hosted-invoice link. The invoice is marked sent after Notify accepts the email dispatch. Provider delivery is confirmed separately in invoice delivery history.
• List invoice delivery attempts: List every Topolo Notify email attempt for one invoice, newest first, including recipient, Notify dispatch status, Nexus delivery receipt status, receipt timestamp and failure detail.
• Mark an invoice manually sent: Record that an approved invoice was sent outside Topolo. This does not send an email and preserves delivery state independently from settlement.
• Generate invoice PDF: Render one saved invoice as a complete multi-page PDF using the published Brand kit bound to its Books workspace. Once online payment has been enabled, its QR opens the stable hosted invoice page, which offers checkout only while money remains due.
• Get public invoice page: Read the active customer-facing invoice page link and its timestamped page-view history without exposing the invoice publicly when no link exists.
• Create public invoice page: Create an opaque, revocable customer-facing page for an approved invoice using the published Brand kit bound to its Books workspace. Repeating the action returns the same active page.
• Revoke public invoice page: Immediately disable the invoice public page and its PDF endpoint without changing the accounting record.
• Void an invoice: Void an invoice while keeping its number and history readable. Its standing document journal is reversed and linked in the immutable ledger. Refused while payments are recorded against it.
• Repair invoice ledger posting: Replace one legacy invoice journal with a reversal and a corrected base-currency posting that retains the document currency and approval exchange rate. Repeating the action returns the standing correction.
• Record a payment: Record money received against an invoice. Any open online checkout is expired before the balance changes, and the document becomes paid once its receipts cover it.
• List invoice payment options: List each exact Topolo Pay provider account enabled to collect an approved invoice in this Books workspace.
• List invoice payment sessions: List the Pay checkout sessions created for an invoice, newest first, including their amount, settlement state and stable Books customer-page URL without exposing the provider checkout URL.
• Create invoice payment link: Create one hosted Topolo Pay checkout through the selected provider account for the invoice outstanding balance and return the stable Books customer-page URL. Repeating the same request returns the existing open session instead of creating another charge path.
• Check invoice payment: Verify a hosted checkout directly with Topolo Pay. A completed payment is recorded once against the invoice and posted through undeposited funds for later payout reconciliation.
• Revoke invoice payment link: Cancel one open Topolo Pay checkout for an invoice so customers can no longer use it. The cancelled link remains in invoice history and a new link can then be created with another enabled provider account.
• Write off invoice balance: Close the whole remaining invoice balance as bad debt or a small residual balance. Bad-debt write-offs post to the selected expense account and can reclaim eligible UK output VAT after six months; small balances up to 1,000 minor units post to rounding.
• List recurring invoices: List recurring invoice schedules, optionally filtered by lifecycle status, including their next and last invoice dates, automation choices, run count and last failure.
• List recurring invoice payment options: List each enabled Pay merchant and the masked saved cards available for one invoice customer in this Books workspace.
• Create recurring invoice: Schedule a complete draft invoice template weekly, monthly, quarterly or annually, with optional end date or occurrence limit, automatic approval and sent-state recording.
• Get recurring invoice: Read one recurring invoice schedule, its template id, cadence, end conditions, automation, run history and last failure.
• Update recurring invoice: Change an active or paused recurring invoice schedule. Existing generated invoices are not rewritten and the complete linked draft remains its template.
• Pause recurring invoice: Pause an active recurring invoice schedule without moving its next invoice date.
• Resume recurring invoice: Resume a paused recurring invoice schedule so the worker can create its next due occurrence.
• Cancel recurring invoice: Permanently cancel an active or paused recurring invoice schedule. Its template and generated invoices remain readable.

Evidence

Actual Books route handlers and the exported Worker were exercised against five local SQLite D1 concern databases with all committed migrations, the real posting Durable Object and local R2. Route captures use synthetic verified Auth; Worker captures use synthetic Auth transports. Nexus, Brand, Notify, Pay, Mercury and Xero responses are explicitly simulated at the provider transport boundary. Captures prove local request/response behavior and canonical SDK projection, not live bank access, payment movement, email delivery, provider eligibility, tax compliance, encrypted custody, scheduled execution, deployment or production completion. Fixture identities, credentials, addresses and records authorize no live operation.