Skip to main content
Technology & EngineeringSystem Design38 lines

Double-entry Billing Ledgers

Model immutable balanced postings, idempotent financial events, reversals and reconciliation for billing systems.

Quick Summary8 lines
Use this skill to design the accounting record behind invoices, payments, credits and refunds. Begin with a chart of accounts reviewed for the business model. Identify currencies, minor-unit precision, settlement timing and ownership of funds. Software correctness does not by itself establish the appropriate accounting treatment.

## Key Points

- [TigerBeetle transfer model](https://docs.tigerbeetle.com/reference/transfer/)
- [Two-phase transfers](https://docs.tigerbeetle.com/coding/two-phase-transfers/)
skilldb get system-design-skills/billing-ledgerFull skill: 38 lines
Paste into your CLAUDE.md or agent config

Double-entry Billing Ledgers

Use this skill to design the accounting record behind invoices, payments, credits and refunds. Begin with a chart of accounts reviewed for the business model. Identify currencies, minor-unit precision, settlement timing and ownership of funds. Software correctness does not by itself establish the appropriate accounting treatment.

Define the journal contract

Balance every journal within one currency: total debits equal total credits. Use integer minor units or a precisely specified decimal representation, never binary floating-point money. Do not offset a dollar debit with a euro credit. Model currency conversion through explicit accounts and rates with provenance.

Each posted journal needs an immutable ID, business-event key, effective time, recorded time, source references and ordered entries. Validate account existence, currency and allowed state before committing the complete journal atomically. A partial journal must never become visible.

Separate pending reservations from posted balances. Define when a reservation expires, posts or is voided, and prevent both posting and voiding the same reservation. Available balance and accounting balance may differ; expose their definitions clearly.

Handle retries and correction

A provider webhook is evidence of an external event, not a command to add money on every delivery. Persist a unique provider/event or business-operation key and verify payload consistency on retries. After an ambiguous timeout, look up the operation before resubmitting it. Do not interpret duplicate-key errors as success without verifying the recorded journal.

Reverse mistakes with new postings linked to the original journal. Preserve the original entries and explanation. For partial refunds, specify how principal, tax, fees and seller liabilities are affected; these may not all reverse proportionally.

Keep invoices, payment attempts, settlement transfers and ledger journals distinct. An invoice marked paid does not prove cash has settled to the bank.

Reconcile and test

Recompute balances from entries and compare them with materialized balances. Reconcile provider transactions to journals and journals to bank settlements using stable identifiers, timing differences and explicit exception categories. Never fix unexplained differences with an unreviewed balancing entry.

Test duplicate events, concurrent credits, partial failure, out-of-order settlement, void-after-post, currency mismatch and negative-balance constraints. Include a concrete small lifecycle from invoice to payment, fee and refund, proving balance after every step.

Deliver the account model, posting rules, event mapping, invariants and reconciliation report. List unresolved accounting decisions for the responsible finance reviewer instead of hiding them in implementation defaults.

References

Install this skill directly: skilldb add system-design-skills

Get CLI access →