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.

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

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 - available credit balances for loaded finance customers - 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 - mark sent, overdue, or partially paid invoices as paid from the same table - 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.

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: - due_days – days until due (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

List Invoices

Get Invoice Detail

Returns invoice with all line items.

Send Invoice

Transitions from draft to sent. This action: 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.

Mark Invoice as Paid

Void Invoice

Voids a non-paid invoice and creates a reversing GL journal entry. Cannot void paid invoices – use a refund 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 draft, sent, overdue, or partially paid invoices. Credits are applied against outstanding balance (total_cents - amount_paid_cents), and invoice settlement fields are normalized after application.

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

AR Aging Report (Finance)

Simple AR aging: unpaid invoices bucketed by age (current, 30-day, 60-day, 90+ day).

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 payments auto-generate GL journal entries: debit Cash (Operating), credit Accounts Receivable.

If GL posting fails on invoice send/mark-paid/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.

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.

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.

Request a Refund

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

Revenue Analytics

MRR History

MRR (Monthly Recurring Revenue) snapshots for the last N days (7-365).

Current Revenue

Latest MRR/ARR, active subscription count.

MRR Breakdown

MRR decomposed: new, expansion, contraction, churned, net new.

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.

LTV Breakdown

Per-plan LTV, lifetime distribution by cohort.

CAC Breakdown

Expense-level CAC breakdown, monthly trend, payback analysis.

Tax Deduction Summary

Deductible expenses grouped by tax category.

Quarterly Tax Estimate (Revenue Module)

Simplified quarterly estimate from the revenue module (separate from the accounting quarterly estimate engine).

Year Tax Summary

Full-year tax summary with quarterly breakdown, SE tax, income tax estimates, and deduction details.

Daily Digest

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