Ledger & settlement | Farther Shore

Every monetary fact on the platform is a balanced ledger posting in nanodollars. Funding buckets, amount due, and the bill preview are views of the ledger, reconciled against it on a schedule. Stripe is the settlement rail: it collects and pays out, and its webhooks are idempotent ledger inputs — never direct balance mutations. Core is the single monetary writer for a subject.

Chart of accounts

Account	Class	Meaning
`CashClearing`	asset	Gross funds the rail has confirmed collected, less confirmed refunds or payouts.
`PrepaidLiability`	liability	Rated-value obligation represented by every live bucket (prepaid, included, promo, referral).
`IncludedAllowanceContra`	contra-revenue	Cost of included value a plan issued; unused expiry credits it back.
`PromoContra`	contra-revenue	Cost of promotional value issued.
`ReferralContra`	contra-revenue	Cost of referral value issued.
`UsageRevenue`	revenue	Rated usage recognized from `RatedCharge` rows; prepaid breakage posts here with role `BREAKAGE`.
`RecurringRevenue`	revenue	Recurring plan fees.
`RoundingDifference`	contra / expense	Customer-favorable value dropped by rating-floor or settlement-quantum flooring.
`SettlementReceivable(rail)`	asset	Exact amount due through a named rail after funding.
`TaxPayable(rail)`	liability	Tax the rail collected and must remit; never rewrites local revenue.
`RefundsPayable`	liability	Cash-backed value approved for return, not yet confirmed paid.
`WriteOff`	expense	Uncollectible receivables, expired non-cash funding on refund, final dispute loss.

Posting templates

One template per event type; every transaction balances to zero:

Rated charge — debit funding bucket(s) in allocation order and/or the rail receivable; credit UsageRevenue.
Recurring fee / commitment true-up — the local agreement clock recognizes it; exactly one settlement export carries it to the rail.
Top-up — pending → available: the bucket is created pending on checkout, funded (CashClearing ↔ PrepaidLiability) when the rail confirms payment.
Grant issuance / expiry — included, promo, referral value debits its contra account on issuance; unused value on expiry credits it back. Prepaid expiry is breakage.
Refund — reverse the original allocation pro-rata per source: prepaid to RefundsPayable, non-cash restored if unexpired else WriteOff; a rail payout later debits RefundsPayable, credits CashClearing.
Settlement export / receipt / void / write-off — the exported receivable is matched byte-for-byte to the Stripe invoice; receipts post gross cash plus tax.
Rating-floor rounding — per-event floors are exact; the window remainder is recognized once and the dropped fraction posts to RoundingDifference.

Rating corrections (late measurements, volume-tier reselection at window close) are correction transactions on the closed window, not refunds.

Machine-checked invariants

Scheduled reconciliation asserts, and alerts on:

every transaction balances;
sum(bucket balances) == ledger liability per subject and source kind;
per rating window, sum(RatedCharge) == revenue + contra postings;
settlement rounding stays within settlements × quantum;
rating-floor rounding equals the exact rational target per window;
gateway value reconciliation: folded per-lease spend equals the usage meter's per-dimension totals.

Nothing edits historical postings to make a predicate pass. Corrections are explicit balanced transactions after the discrepancy is understood.

Two kinds of stop

State	Scope	Effect	Cleared by
`SettlementAccount.state = RECONCILIATION_REQUIRED`	one subject	Monetary admission denied for that subject; rating continues.	Scheduled reconciliation proving ledger, buckets, expected rail operations, and Stripe agree.
`SettlementHold(reason)`	one rating window or event	Export for that window blocked; unrelated rating and admission continue.	The reason-specific reconciler (`admission_bound_breached`, `accounting_divergence`, quarantine, …).

Triggers for RECONCILIATION_REQUIRED: a rail-initiated refund, dispute, or early-fraud warning matching no expected local operation; a top-up success after cancellation; a Stripe invoice that does not match its local export; bucket/liability or rail/cash divergence.

Sequence gaps in the usage pipeline hold settlement, never rating: a quarantined event writes a terminal record that closes its hole; late events are correction transactions.

What Stripe never does

Stripe never rates usage, chooses funding, owns a balance, or mutates a bucket. No subscriber balance and no meter lives in Stripe. invoice.upcoming is never a monetary input. Only one webhook family is authoritative for each transition (Checkout success for top-ups, invoice.paid for cash receipt, refund.* for payouts, charge.dispute.* for disputes).

Reading the state

Subscriber-facing totals: the bill preview.
Builder-facing usage: farthershore usage summary <business> and the dashboard's usage and plans views (catalog and release, never subscriber bills).
Release identity for any admitted request rides the signed usage event; the Apply Timeline and workflow views show publication and activation history.

Continue with Diagnose billing and usage.

Ledger & settlement | Farther Shore

Chart of accounts#

Posting templates#

Machine-checked invariants#

Two kinds of stop#