Finance

Scope

Finance inside Keystone is about keeping the operating truth legible to the people responsible for it. This guide preserves that public-safe operating model and removes implementation detail.

Apply customer credits by business date

From Finance or invoice detail, choose Apply credit, confirm the legal entity, and select the effective date. Keystone preserves the date and command identity after a recoverable error. Retry the same command after opening the required fiscal period or correcting authority; do not submit a new command merely because the first response was lost.

One action applies all safe eligible credit needed for the invoice through bounded server work. The final result may summarize a large credit population, but its applied count and invoice balance are authoritative. A chronology conflict means a later application already consumes the historical capacity; reverse or re-date the later application before retrying.

Invoice creation, payments, credits, refunds, revenue analytics, and finance workspace execution.

The dashboard separates subscription analytics from accounting truth. Recurring contribution signal is MRR minus recorded operating expenses for the displayed periods; it is not revenue or net income. Use its View authoritative P&L and net income link for ledger-backed profit and loss. Do not compare the MRR signal directly with P&L revenue.

Expense makers cannot claim, approve, hold, or reject their own submissions. Their row states that another expense approver must claim and decide the item; a different signed-in operator with keystone.expenses.approve uses the team approval queue to claim it. The Expenses workspace heading has human-readable English fallback copy, so delayed or missing locale initialization cannot expose translation keys on this primary finance surface.

Refund requests follow the same visible maker-checker handoff. Submitting a request creates a work notification for a different operator with keystone.finance.manage. Approvers can open that notification directly or use the Review refund queue banner on Invoices, then choose Return to payment method, Issue customer credit, or a reasoned rejection in the Finance queue.

Workspace And Settlement Clarity

Every authenticated page shows the active Keystone authority directly below the application header: company name, Portal tenant ID, active/default legal entity, signed-in operator, and a Verify workspace action. Use that action when the tenant or company is not the one you expected; it returns through the Portal sign-in authority instead of changing tenant scope inside Keystone. After successful Portal reauthentication, Keystone returns to the route, filters, and selected record that initiated the handoff.

Invoice settlement uses one operator workflow: Record payment. Enter the amount actually received, payment method, date, and optional reference. Keystone creates the payment record, applies it to the invoice, posts the accounting effect, and refreshes invoice and payment history together. The amount defaults to the outstanding balance for partially paid invoices. Finance invoice rows route to the same payment form; there is no separate status-only “mark paid” action in the UI.

Resolving a collections action also resolves its active invoice dunning notification. Communications therefore shows only active recovery work; the notification remains durably stored with its resolution timestamp and reason for audit evidence.

Finance Workspace

Route: the relevant workflow

The finance workspace is the primary operator landing surface for finance review work and routed execution.

What the workspace shows:

• current revenue posture
• AR aging and recent invoice exposure
• recent payments
• a server-paginated available-credit register across the tenant, with a complete total that does not change when the visible page changes
• pending refunds awaiting approval decisions
• current-year tax cash movement plus recent tax payments
• unresolved dunning items with failure-reason and recovery-cohort summaries

What finance-manage users can do inline:

• send draft invoices from the recent invoice table
• open the canonical payment form for sent, overdue, or partially paid invoices
• apply available credit to eligible invoices from the recent invoice table
• issue customer credits from the relevant workflow
• approve or reject pending refunds from the relevant workflow
• resolve unresolved dunning items from the collections watchlist
• reschedule unresolved dunning items by 1, 3, or 7 days from the same watchlist
• escalate eligible dunning items from the watchlist into the next recovery step

What still stays outside this workspace:

• no customer self-service billing launch

Finance-view users can still open the relevant workflow, but the invoice and collections action controls stay hidden and the page remains read-only for them. All authenticated reads that power this page run through tenant-scoped request sessions on the backend. Operators never pass tenant IDs manually for invoices, dunning, revenue cards, or finance workspace tables.

The credit table uses one aggregate backend request and includes the customer name returned with each balance. Paging the table does not change the total available-credit card. A failed credit-register request appears as a scoped workspace error instead of triggering one failure per customer or presenting a partial page as the tenant total.

Credit issuance uses a searchable customer selector rather than a numeric customer ID. In Finance, candidates are server-filtered to the active company-entity scope before selection. Changing legal entity clears the previous customer immediately, invalidates older lookup responses, and keeps Issue Credit disabled until you choose a customer verified in the new entity. Search results expose only the customer name, billing email, active state, and internal ID needed by the mutation. A missing scope or directory failure remains visible with retry instead of becoming an empty customer list; other entered credit fields remain available for recovery. Inactive customers are labeled explicitly so post-churn adjustments remain possible without making dormant accounts look current. The selector requires the same finance-manage or billing-manage authority as credit issuance and cannot return another tenant’s customer.

Use the handoff links for deeper review:

• the relevant workflow for customer-specific AR balance, invoice balances, payments, and available credit in one workspace
• the relevant workflow for detailed revenue analytics
• the relevant workflow for invoice detail
• the relevant workflow for deeper customer-scoped credits, refunds, and collections history/detail
• the relevant workflow for tax-specific detail

Some handoff links only appear when your role includes the matching permission. The workspace itself requires keystone.finance.view.

Invoicing

Create an Invoice

Fields:

• issued_on – optional invoice business date; use this to enter a legitimate historical receivable
• due_on – optional explicit due date; must be on or after the invoice date
• due_days – compatibility fallback used when due_on is omitted (default: 30, range: 1-365)
• notes – optional
• lines (required, at least one) – array of line items:
• description (required)
• quantity – defaults to 1
• unit_price_cents
• sort_order

Invoices are created in draft status. The system auto-generates an invoice number (INV-YYYYMM-NNNN) and calculates:

• subtotal_cents – sum of all line amounts
• tax_cents – calculated from the default active tax rate (unless customer is tax-exempt)
• total_cents – subtotal + tax

After creation, the routed UI opens the new invoice detail instead of returning the operator to an undifferentiated list. The detail keeps the draft’s Send, PDF, and void controls with the customer and line-item evidence so the next lifecycle step is explicit. Payment, credit application, and write-off controls appear only after successful issuance creates authoritative open AR.

The invoice workspace is permission-aware. Finance or billing managers can create, send, record payments, apply credits, void, and generate PDFs. Refund requests require finance management authority. Issuing a customer credit creates an entity-scoped approval request; it does not increase available credit or post a journal until independently approved. A write-off requires both finance-management and accounting-management authority, then also creates an entity-scoped approval request. View-only operators see an explicit read-only state and no mutation controls, including when they arrive through a payment deep link. If invoice loading fails, the workspace shows the actual error with a retry action instead of presenting a false empty ledger.

The operator form asks for invoice and due dates directly. Backdated dates remain stable across browser time zones and provide a safe way to compose overdue collections work without fake negative payment terms. The invoice date is also the authority for historical sales-tax resolution and the issuance journal period. A future-dated draft cannot be sent, and a due date before the invoice date is rejected inline and by the API. Invalid customer, entity, date, or line-description input stays in the create dialog; backend rejection is also retained instead of disappearing into a transient notification.

When creating a close run, select an open fiscal period. Submitting without one marks the field invalid and leaves a persistent explanation in the dialog; when no open periods exist, create or reopen the required period from Financial Statements before retrying.

List Invoices

This mounted read stays tenant-scoped through the authenticated request session; a signed-in operator should not see a tenant bootstrap or RLS wiring error here.

Get Invoice Detail

Send Invoice

1. Sets issued_at timestamp
2. Auto-generates a PDF if not already generated
3. Creates GL journal entries: debit Accounts Receivable, credit Revenue + Sales Tax Payable

Only draft invoices can be sent.

If posting is blocked, the invoice stays in Draft and its detail page keeps a visible Invoice was not sent message with the exact accounting invariant. Missing or closed fiscal periods preserve the server-provided recovery action, including the required month and company entity when a period must be created; correcting the period and retrying is required rather than bypassing the ledger control.

Settle an Invoice with a Recorded Payment

The Paid amount shows the exact server amount_paid_cents value, including partial payments; it is not the full-payment date. The Outstanding amount on an issued invoice comes from immutable receivable history, not the displayed paid/credit caches. If it reads Unavailable, Keystone disables payment, credit, and write-off actions. Retry the workspace after restoring the reported history or dependency; do not infer and enter the difference manually.

Void Invoice

Voiding a draft creates no accounting entry. Voiding an issued, unsettled invoice reverses its original journal entry and closes the receivable at the same UTC effective instant. Partially paid and paid invoices cannot be voided; use credit/refund workflows instead.

Generate Invoice PDF

Generates and stores a PDF. Returns the PDF as a download.

Download Invoice PDF

Apply Credits to Invoice

Auto-applies available customer credits (oldest/soonest-expiring first) to sent, overdue, or partially paid invoices. Credits are applied against the immutable receivable-event balance, and invoice settlement cache/status fields are updated in the same transaction. Invoice detail resolves the resulting posted credit-application journal by the receivable-event ID within the invoice’s exact tenant and legal entity, exposing its journal number without accepting a same-ID journal from another scope or source.

Returns a detailed breakdown of which credits were applied and the new invoice total.

AR Aging Report (Finance)

Simple AR aging shows five non-overlapping buckets: Current, 1-30, 31-60, 61-90, and 91+ days. Day 90 remains in the 61-90 bucket; 91+ means strictly greater than 90 days. An invoice without a due date remains Current and is never counted as overdue. The five displayed amounts sum to Total. The API retains the legacy wire field ninety_plus_cents for the final 91+ range and also returns ninety_days_cents for 61-90.

Payments and Credits

Record a Payment

Fields:

• amount_cents (required, > 0)
• reference_number – check number, wire reference, etc.
• payment_date (required)
• notes

For completed invoice-linked payments, Keystone applies the amount to invoice amount_paid_cents and transitions the invoice:

• partial coverage -> partially_paid
• full coverage -> paid

Overpayments beyond outstanding balance are rejected.

Completed operator-recorded payments auto-generate GL journal entries: debit Cash (Operating), credit Accounts Receivable, and persist the exact receivable-event and journal links on the Payment. An identical retry returns that same Payment and evidence chain. Confirmed Stripe payments are different: until payout/bank evidence exists they debit the exact configured Stripe clearing asset, never Operating Cash, and appear in the same payment register with provider, receivable-event, journal, and clearing lineage.

If GL posting fails on invoice send/payment record/credit issue/refund approval, Keystone rolls back the mutation and returns an error instead of committing partial finance state.

List Payments

Issue a Credit

Fields:

• amount_cents (required, > 0)
• reason
• expires_at – optional expiration

Credits auto-generate GL journal entries: debit Revenue, credit Customer Credits.

Apply-credit has the same recovery contract. When its outcome is unknown, choose Retry Apply Credit on that invoice. Keystone prevents starting an application on another invoice until the uncertain command is resolved, because the original request may already have committed. Do not reconstruct the amount manually or create a replacement credit to work around a timeout.

View Credit Balance

Returns total available (non-expired, non-exhausted) credits.

List Credits

A. Collections / Dunning

View the Collections Watchlist

Returns unresolved dunning items with:

• customer name when known
• billing email fallback
• event type
• attempt number
• failure reason code
• recovery campaign key and version
• next retry date
• notes

The the relevant workflow workspace pages through this response to render the collections watchlist plus operator-facing failure-reason and recovery-cohort summaries. Older rows created before the intelligence fields were stamped may show as unclassified or legacy cohorts; that is intentional and truthful. Like the other mounted finance reads, this watchlist route depends on the tenant-scoped authenticated request session rather than a tenant query parameter.

Resolve a Dunning Item

Fields:

• notes – optional operator note

Marks an unresolved dunning action as handled by finance. The mutation writes audit action keystone.finance.dunning.resolved.

Reschedule a Dunning Item

Fields:

• next_retry_at (required) – future timestamp
• notes – optional operator note

Moves the next retry for an unresolved dunning action. The the relevant workflow workspace offers 1-day, 3-day, and 7-day shortcuts and writes audit action keystone.finance.dunning.rescheduled.

Escalate a Dunning Item

Fields:

• notes – optional operator note

Refunds

List Refund Queue (Tenant)

Filters:

• limit
• offset

The the relevant workflow workspace uses this endpoint to show and action pending refunds without routing through the relevant recovery workflow.

An accounting journal drill uses exact approved or pending refund independently of the pending queue’s page. Keystone shows a retryable unavailable state when that scoped dependency fails; it does not treat absence from the pending queue as proof that the refund is missing.

Request a Refund

After a request is submitted, the paid invoice row shows the durable refund number, pending-approval status, requested amount, request date, and that a different finance operator must decide it. While that request is pending, Keystone removes the duplicate request action. Select Open refund queue to open and highlight the exact request in Finance for maker/checker approval or rejection.

Fields:

• amount_cents (required, > 0)
• reason (required)
• notes

Created in pending status. Requires approval.

Approve a Refund

Approving a refund:

1. Sets status to approved
2. Auto-creates a credit for the refund amount (type: refund)
3. Posts GL journal entry: debit Revenue, credit Cash

Reject a Refund

List Refunds

Recurring Revenue Counts

The Revenue workspace requires one selected company entity and shows only active and trial subscription counts. It deliberately withholds MRR, ARR, ARPU, plan prices, movement waterfalls, and revenue-churn money while recurring plan prices lack immutable transaction and functional-currency evidence. A warning is not a zero: use the displayed retry action if count evidence cannot be read.

MRR History

Returns the exact entity plus recurring_currency_status="unavailable" and no monetary history until the cross-product price contract is accepted.

Current Revenue

Exact-entity active and trial subscription counts. Currencyless snapshots and mutable plan price cents are not displayed or exported as recurring money.

MRR Breakdown

Returns a typed unavailable recurring-currency response; Keystone does not calculate or infer a waterfall without immutable price evidence.

Cohort Analysis

Customer cohort analysis by signup month.

Churn Analytics

Logo churn rate, revenue churn rate, churn reason breakdown.

Churn Reasons

Aggregate of cancellation reasons.

Unit Economics

LTV (Lifetime Value), CAC (Customer Acquisition Cost), payback period, gross margin. These mounted revenue reads execute inside the tenant-scoped authenticated request session so LTV/CAC cards remain valid under RLS. On the root Dashboard, current revenue, LTV, CAC, AR aging, expense summary, and AP aging all use the company named at the top of the page. A parent-company view includes its active subsidiaries; the default company view also includes older unassigned transition records. Standalone finance pages retain their documented scope unless they explicitly request dashboard scope. This does not apply to Accounting Financial Statements or Accounting AR Aging: those ordinary financial reports require one exact active entity and never use dashboard default, rollup, unassigned, or tenant-wide semantics. Company-scoped current revenue is calculated live from current subscriptions. Expansion, contraction, churn, and net-new movement remain unavailable because the persisted history is all-company; Keystone does not display those tenant movements as company values. An unknown or inactive selection is reported as not found. Incomplete company access is reported as Access required with instructions to select a narrower assigned company or request access to every subsidiary in the rollup.

The Revenue workspace labels each metric source as current snapshot, stale snapshot, missing snapshot, or live entity-scoped. A stale snapshot remains visible with its as-of date; a missing snapshot withholds MRR, ARR, and movement values rather than showing zero; a live entity-scoped result identifies that movement history is unavailable. Current subscription and snapshot records do not yet carry a verified recurring-revenue currency authority, so the Dashboard withholds MRR, ARR, net-new MRR, LTV money, LTV:CAC, and payback money while retaining non-monetary customer and lifetime evidence. If the API returns contradictory freshness, currency, or LTV-confidence evidence, Keystone treats that section as unavailable instead of presenting a financial value.

LTV Breakdown

Per-plan LTV, lifetime distribution by cohort. Each plan row has a stable typed contract with plan identity, customer count, MRR, measured lifetime, LTV, confidence, and the number of cancelled subscriptions used; insufficient history is shown as unavailable rather than zero.

The dashboard displays the LTV confidence and the exact cancelled-subscription count. It does not calculate or grade LTV:CAC until actual confidence is supported by cancellation history.

Period-end currency revaluation posts each unrealized gain or loss only inside the selected legal entity and its open fiscal period. If that scope has no valid period or exchange rate, Keystone leaves the ledger unchanged and reports the exception instead of posting into another entity.

CAC Breakdown

Expense-level CAC breakdown, monthly trend, payback analysis. Company-scoped CAC applies the same company selection to acquisition spend, new-customer counts, trend values, and average revenue. If access is incomplete, the Dashboard shows Access required and a recovery instruction instead of combining company spend with all-company customer counts.

Tax Deduction Summary

Deductible expenses grouped by tax category for one active company entity. The typed response includes the exact entity, functional currency, population count, unavailable count, and currency status. When any Expense evidence is legacy, incomplete, or mismatched, Keystone returns a typed unavailable result with no monetary groups instead of a partial total.

Quarterly Tax Estimate (Revenue Module)

Year Tax Summary

Full-year tax summary with quarterly breakdown, SE tax, income tax estimates, and deduction details for one required active company entity. Every quarter repeats the same exact entity and functional currency. Keystone rejects contradictory or incomplete Expense or journal currency evidence; it never substitutes the current profile currency onto historical rows or presents the incomplete population as zero.

Daily Digest

Daily financial summary: new revenue, payments, expenses, and key metrics.

Cash And Collections Recovery

The Finance workspace shows payment reference numbers and preserves customer and invoice context when opened from an overdue invoice. An exact invoice handoff shows only recovery actions for that invoice. Sending an already-due invoice creates the first idempotent internal collections action immediately; normal dunning automation continues from that durable intake row.

After resolving, rescheduling, or escalating a collections action, use Continue in Communications. The handoff retains the customer, invoice, dunning action, and outcome; Communications displays that context and provides a return link to the same collections scope.

Invoice detail is the settlement workspace for an individual invoice. It lists each recorded payment with its business date, method, status, amount, and external reference. The Supporting Evidence section lists customer-classified attachments and lets document managers upload and attach evidence without leaving the invoice.

Cash Flow Projection uses the same authoritative company scope and as-of date as Cash Position. Both cards disclose scope and basis, and Keystone refuses to present them as comparable if those response contexts differ. Tenant-wide projection includes tenant cash, invoices, and bills. Entity/default-scope projection filters cash and invoices by entity and omits bills until bill-level legal-entity attribution exists; that limitation is visible in the returned assumptions and data sources. When no usable scoped cash history or known items exists, Keystone returns an actionable 422 instead of presenting a fabricated forecast.