November 2024: a ledger that cannot be quietly edited

Part 14 of 39 of Building TradeYoke, the story of how the platform was built, from January 2024 to today. Previous: October 2024: why invoicing came next, and what it had to get right. Next: December 2024: part payments, receipts and knowing who owes you. See every part on the build timeline.

Quick answer: TradeYoke's invoicing ledger is append-only: entries are added and never rewritten, and a correction is a new entry that reverses or adjusts the old one. That means the history of every invoice, payment and credit is always visible, and balances and ageing are worked out from the same record rather than stored separately.

• The ledger only adds entries; it never edits or deletes them.
• A correction is a new entry, so the history stays visible.
• Balances and ageing are worked out from the ledger, so they cannot disagree with it.
• Payments that do not match exactly have three clear resolutions: over, short and unmatched.

The obvious way to build invoices is to store them and let people edit them. It is simple and it goes wrong in a very ordinary way: someone changes an amount, the customer's statement no longer matches what they were sent, and nobody can say who changed what or when. For a small business, that is a dispute you cannot easily win.

In November 2024 we built the invoicing core as a ledger. Every event (an invoice issued, a payment received, a credit given) is added as a new entry. Nothing already written is changed or removed. If something was wrong, you add an entry that corrects it, and the original stays where it was.

• A history you can read. For any customer you can see exactly what happened, in order.
• Balances that cannot disagree. What a customer owes, and how old the debt is, are worked out from the ledger when needed. They are not a second copy that might drift.
• Safe retries. Each entry has a key so that a payment notification arriving twice is recorded once.
• Three honest ways to deal with odd payments. When a payment is more than the invoice, less than the invoice, or cannot be matched to one, there are three defined resolutions, not a silent guess.

Another design choice: anything in TradeYoke that earns money does so through one doorway. A window cleaning visit, a gardening job or a certificate hands its amount to the invoicing module; it does not write to the ledger itself. That keeps the rules in one place. It is also why credit notes, late fees and statements, which came later, could be built on the ledger without special cases.

An append-only design is more work to build than an editable table. We think the work is worth it when it means a customer's statement always agrees with what they were sent. Next month: part payments, receipts and the first version of "who owes me".

Related: Invoicing and payments · Who owes me · Invoice fraud and account protection · Pricing · The build timeline