DEV Community: ZeraBooks

Designing an AI general ledger: the model proposes, deterministic code disposes

Damin Mutti — Sat, 24 Oct 2026 05:09:37 +0000

An AI general ledger works when the model only produces proposals (a category, a match, a question with a confidence) and deterministic code validates, applies, logs and can reverse them. Every balance and total comes from the ledger, never the model. That is how ZeraBooks is built. This post sketches that shape in TypeScript. It illustrates the design; it isn't our source code.

I'm on the ZeraBooks team. When people hear "AI does the bookkeeping" they picture a model writing journal entries. That's the design we avoided. The model never writes to the ledger and never does arithmetic. It returns a small structured proposal, and everything after that is ordinary code with tests.

Proposals, not writes

type Confidence = "sure" | "fairly_sure" | "not_sure";

type Proposal =
  | { kind: "categorize"; lineId: string; categoryId: string;
      confidence: Confidence; p: number; evidence: string }
  | { kind: "match_invoice"; lineId: string; invoiceId: string;
      confidence: Confidence; p: number; evidence: string }
  | { kind: "pair_transfer"; outLineId: string; inLineId: string;
      confidence: Confidence; p: number; evidence: string }
  | { kind: "ask"; lineId: string; question: string;
      options: { label: string; categoryId: string; p: number }[] };

Note what's missing: amounts. A categorize proposal says which account a statement line belongs to. The amount is already on the line, read from the statement. A match_invoice proposal says which invoice; the ledger decides whether the amounts agree. There's no field where the model could put a number that ends up in the books.

evidence is a short string quoting what the model relied on ("same vendor and amount as the last eight months"), shown to the user.

A policy layer that can say no

function admit(p: Proposal, ctx: LedgerContext): Decision {
  if (p.kind === "ask") return { action: "queue_question" };

  const line = ctx.line(p.kind === "pair_transfer" ? p.outLineId : p.lineId);

  if (ctx.isClosedPeriod(line.date)) return { action: "reject", why: "closed period" };
  if (line.setByUser)                return { action: "flag_only", why: "user decision stands" };
  if (line.payeeIsTaxAuthority)      return { action: "queue_question", why: "tax payments always ask" };
  if (p.kind === "pair_transfer" && line.isTransfer) return { action: "reject", why: "already paired" };

  switch (p.confidence) {
    case "sure":        return { action: "apply" };
    case "fairly_sure": return { action: "apply_and_flag" };
    case "not_sure":    return { action: "queue_question" };
  }
}

These rules mirror the guardrails we publish: the AI doesn't overwrite a category you set, doesn't touch closed periods, and always asks about payments to a tax authority. They're plain if statements on purpose. You can read them, test them and be sure they hold.

Possible duplicates get their own path: the model can flag a pair, and there is no proposal type for deleting a line at all. Same for moving money: no bill pay, no transfers, no bank connection. The safest permission is the one that doesn't exist.

Every applied action is reversible

interface ActionLog {
  id: string;
  at: string;
  proposal: Proposal;
  before: Snapshot;   // the fields this action changed, as they were
  after: Snapshot;
  undoneAt?: string;
}

function apply(p: Proposal, ctx: LedgerContext): ActionLog {
  const before = ctx.snapshot(p);
  ctx.write(p);                // validated, transactional
  const after = ctx.snapshot(p);
  return ctx.log({ proposal: p, before, after });
}

function undo(log: ActionLog, ctx: LedgerContext) {
  if (!ctx.unchangedSince(log)) throw new Error("line edited since; review manually");
  ctx.restore(log.before);
  ctx.markUndone(log.id);
}

In the product this is the "Done by AI" list. Each card has Undo. unchangedSince prevents an undo from clobbering a later human edit.

Arithmetic lives in the ledger

The month-close check is a pure function over data the model never touched:

function statementTies(s: Statement, prev?: Statement): TieResult {
  const sum = s.lines.reduce((acc, l) => acc + l.amountCents, 0);
  const adds    = s.openingCents + sum === s.closingCents;
  const follows = !prev || prev.closingCents === s.openingCents;
  const agrees  = ledgerBalanceCents(s.accountId, s.endDate) === s.closingCents;
  return { adds, follows, agrees, ok: adds && follows && agrees };
}

Integer cents, no floats. A fictional October checking statement: opening 800000, lines summing to +117945, closing 917945. It adds. If last month closed at 800000, it follows. If the ledger balance at October 31 is 917945, it agrees, and only then can the month be signed off. When it doesn't tie, the model can be asked to re-read the statement, but its proposed fixes are only accepted if they make all three checks pass.

Where confidence comes from

In ZeraBooks, confidence comes from the company's own reviewed history: how lines like this one were categorized before. Below 60%, the question card says the best guess is a low-confidence one. Corrections become history, and the user can apply a correction to similar lines (same merchant, same direction, any account or date), with hand-set lines skipped.

The published accuracy number for this setup: after a couple of months of bookkeeping, ZeraBooks categorizes 99.6% of transactions correctly, tested on years of bookkeeping for several companies. The design goal is that the remaining errors are visible, explained and undoable.

The product

ZeraBooks is an AI-native general ledger. It works from uploaded statements (PDF or CSV, no bank feeds), proves each one against its printed balances to the cent, and costs $79 a month billed annually or $149 monthly after a 7-day trial. The non-technical explanation, including how this differs from a feed-and-rules ledger, is on our page about the AI general ledger.

Disclosure: I'm on the ZeraBooks team, and this describes our product.

Splitting loan payments into principal and interest with Decimal, and generating the journal entries

Damin Mutti — Sat, 24 Oct 2026 05:05:27 +0000

To split a loan payment into principal and interest in code, compute each month's interest as the outstanding balance times the annual rate divided by 12, rounded to the cent, and treat the rest of the payment as principal. Then emit a balanced journal entry per payment and check the running balance against the lender's statement. ZeraBooks' ledger does the same thing in its own code, never in the AI.

I'm on the ZeraBooks team. Loan payments are a nice small example of a rule we hold to everywhere: the AI decides what a bank line is ("this is a payment on the equipment loan"), and deterministic code does the math. Here's that code, simplified, in Python.

Payment amount

For a fixed-rate amortizing loan, the level payment is the standard annuity formula:

from decimal import Decimal, ROUND_HALF_UP, getcontext

getcontext().prec = 28
CENT = Decimal("0.01")

def level_payment(principal: Decimal, annual_rate: Decimal, months: int) -> Decimal:
    r = annual_rate / 12
    if r == 0:
        return (principal / months).quantize(CENT, ROUND_HALF_UP)
    p = principal * r / (1 - (1 + r) ** -months)
    return p.quantize(CENT, ROUND_HALF_UP)

pay = level_payment(Decimal("24000"), Decimal("0.06"), 24)
assert pay == Decimal("1063.69")

Fictional loan: 24,000.00 at 6% fixed over 24 months. Decimal with an explicit rounding mode matters. Floats can drift a cent somewhere over 24 periods, and a one-cent drift means your loan balance never matches the lender's.

The schedule

from dataclasses import dataclass

@dataclass
class Period:
    n: int
    payment: Decimal
    interest: Decimal
    principal: Decimal
    balance: Decimal

def schedule(principal, annual_rate, months, payment=None):
    payment = payment or level_payment(principal, annual_rate, months)
    bal, out = principal, []
    for n in range(1, months + 1):
        interest = (bal * annual_rate / 12).quantize(CENT, ROUND_HALF_UP)
        prin = payment - interest
        if n == months:              # last payment absorbs rounding
            prin = bal
            payment = prin + interest
        bal -= prin
        out.append(Period(n, payment, interest, prin, bal))
    return out

for p in schedule(Decimal("24000"), Decimal("0.06"), 24)[:3]:
    print(p.n, p.interest, p.principal, p.balance)

Output:

1 120.00 943.69 23056.31
2 115.28 948.41 22107.90
3 110.54 953.15 21154.75

Interest on period 1 is 24,000.00 × 0.06 / 12 = 120.00. Three payments total 3,191.07: 345.82 interest and 2,845.25 principal, and 24,000.00 − 2,845.25 = 21,154.75.

The last-period adjustment is there because rounding each month's interest leaves a few cents unaccounted for by the end. Lenders do the same thing; the final payment is usually slightly different from the rest.

Journal entries

Each payment becomes one entry with a debit to the loan, a debit to interest expense, and a credit to the bank. Optional fee lines get their own account:

def payment_entry(period: Period, date: str, loan_acct: str,
                  bank_acct: str, fee: Decimal = Decimal("0")):
    lines = [
        {"account": loan_acct, "debit": period.principal, "credit": Decimal("0")},
        {"account": "Interest Expense", "debit": period.interest, "credit": Decimal("0")},
    ]
    if fee:
        lines.append({"account": "Bank and Loan Fees", "debit": fee, "credit": Decimal("0")})
    lines.append({"account": bank_acct, "debit": Decimal("0"),
                  "credit": period.payment + fee})
    dr = sum(l["debit"] for l in lines)
    cr = sum(l["credit"] for l in lines)
    assert dr == cr, f"unbalanced entry: {dr} vs {cr}"
    return {"date": date, "lines": lines}

The assertion is cheap and catches every bug where someone adds a fee to the bank line but not to the debits. The credit to the bank must equal the withdrawal on the bank statement, same amount and same date, so the bank reconciliation is unaffected.

When the lender's numbers win

The formula above assumes interest is charged monthly on the balance. Many lenders compute it daily, so a payment made late carries a bit more interest. If the lender's statement prints "applied to interest" and "applied to principal", use those numbers and let your schedule be the fallback:

def reconcile_to_lender(book_balance: Decimal, lender_balance: Decimal):
    diff = book_balance - lender_balance
    if diff:
        raise ValueError(f"loan off by {diff}: a payment or split is wrong")

Run that after every payment. It's the loan equivalent of a bank reconciliation, and it's the check people skip.

How ZeraBooks does it

In ZeraBooks, a loan payment on the bank statement is booked to the loan account. At month end, Autopilot asks for the rate if it doesn't know it (it offers 3.75% for an SBA EIDL), then moves that month's interest from the loan to Interest Expense: balance owed × rate ÷ 12. It never splits interest from a guessed rate, and each entry appears in Done by AI with Undo. Loan statements uploaded alongside bank statements are used as evidence for the split. At year end, it flags any loan that got six or more payments with no interest recorded.

Pricing: $79/month billed annually or $149/month billed monthly, 7-day trial. Nothing connects to a lender or bank; statements are uploaded.

The accounting side, with the entries for funding, an origination fee and a late fee, is in our guide on how to record loan payments.

Disclosure: I work on ZeraBooks.

A pre-flight validator for QuickBooks Online bank CSV uploads

Damin Mutti — Sat, 24 Oct 2026 04:57:49 +0000

A QuickBooks Online bank CSV should be validated before upload against two sets of rules: Intuit's format rules (3 or 4 columns, 1,000 lines or fewer, 350 KB or less, one date format, no zeros in Credit or Debit) and the statement's own arithmetic (opening plus rows equals closing). Below is a small Python validator for both. ZeraBooks Convert runs the arithmetic check before it lets you download.

I'm on the ZeraBooks team. Our converter outputs QuickBooks-ready CSVs, so we spend a lot of time on what QuickBooks Online will and won't accept, and on what it will accept that's still wrong. The second category is the dangerous one. A file that uploads cleanly can still be missing a line, and once it's in the For review list you won't see it until reconciliation fails.

Intuit's rules, as checks

From Intuit's help article on manually uploading transactions (updated August 24, 2026):

3 columns: Date, Description, Amount. Or 4: Date, Description, Credit, Debit.
File size 350 KB or less, up to 1,000 lines per upload.
One date format throughout.
In the 4-column layout, leave the empty side blank, not zero.
Don't put the word "amount" in the Credit or Debit headers.

Here they are as code:

import csv, io, os, re
from datetime import datetime
from decimal import Decimal, InvalidOperation

MAX_BYTES = 350 * 1024
MAX_ROWS = 1000
DATE_FORMATS = ["%m/%d/%Y", "%d/%m/%Y", "%Y-%m-%d"]

def detect_date_format(values):
    for fmt in DATE_FORMATS:
        try:
            for v in values:
                datetime.strptime(v, fmt)
            return fmt
        except ValueError:
            continue
    return None

def money(s):
    s = s.strip().replace(",", "")
    if s == "":
        return None
    try:
        return Decimal(s)
    except InvalidOperation:
        raise ValueError(f"not a number: {s!r}")

def validate_qbo_csv(path):
    errors = []
    if os.path.getsize(path) > MAX_BYTES:
        errors.append(f"file is {os.path.getsize(path)} bytes, limit {MAX_BYTES}")

    with open(path, newline="", encoding="utf-8-sig") as f:
        rows = list(csv.reader(f))
    header, data = rows[0], rows[1:]
    if len(data) > MAX_ROWS:
        errors.append(f"{len(data)} rows, limit {MAX_ROWS}; split by date")

    cols = [h.strip().lower() for h in header]
    if len(cols) == 3:
        layout = "3col"
    elif len(cols) == 4:
        layout = "4col"
        for h in cols[2:]:
            if "amount" in h:
                errors.append(f"header {h!r} must not contain 'amount'")
    else:
        return [f"expected 3 or 4 columns, got {len(cols)}"], None

    fmt = detect_date_format([r[0] for r in data])
    if fmt is None:
        errors.append("dates are not in one consistent format")

    signed = []
    for n, r in enumerate(data, start=2):
        if layout == "3col":
            amt = money(r[2])
            if amt is None:
                errors.append(f"line {n}: empty amount")
                continue
        else:
            cr, dr = money(r[2]), money(r[3])
            if (cr is None) == (dr is None):
                errors.append(f"line {n}: needs exactly one of Credit/Debit")
                continue
            if (cr is not None and cr == 0) or (dr is not None and dr == 0):
                errors.append(f"line {n}: use a blank, not 0")
            amt = cr if cr is not None else -dr
        signed.append(amt)
    return errors, signed

detect_date_format checks that one format parses every row. Mixed formats are common when someone pastes two exports together. A file where 03/04/2026 is ambiguous will still pass; that's a limit of looking at strings, and why the next check matters more.

The check Intuit doesn't run: does the file tie?

QuickBooks has no way to know your statement's balances. You do. Opening balance plus every signed row should land on the printed closing balance:

def ties(signed, opening, closing):
    total = opening + sum(signed, Decimal("0"))
    return total == closing, total - closing

A fictional quarter: checking ending 2290, July to September 2026, in one PDF. Opening 8,214.55, deposits 31,402.10, withdrawals 29,880.43, closing printed as 9,736.22.

errors, signed = validate_qbo_csv("chk_2290_2026Q3.csv")
ok, diff = ties(signed, Decimal("8214.55"), Decimal("9736.22"))
print(errors or "format ok", "| ties" if ok else f"| off by {diff}")

8,214.55 + 31,402.10 − 29,880.43 = 9,736.22. If diff isn't zero, don't upload. A diff equal to one row's amount means that row is missing or doubled. A diff of twice a row means its sign is flipped.

Splitting a big year

A busy account can blow through 1,000 rows. Split on month boundaries, not at row 1,000, so each chunk starts and ends on a statement date and can be tied on its own:

from collections import OrderedDict

def split_by_month(rows, date_fmt, max_rows=MAX_ROWS):
    months = OrderedDict()
    for r in rows:
        key = datetime.strptime(r[0], date_fmt).strftime("%Y-%m")
        months.setdefault(key, []).append(r)
    chunks, current = [], []
    for key, mrows in months.items():
        if current and len(current) + len(mrows) > max_rows:
            chunks.append(current)
            current = []
        current.extend(mrows)
    if current:
        chunks.append(current)
    return chunks

1,640 rows over a year, for example, comes out as two files of whole months. If a single month is over 1,000 rows on its own, you'll need to split inside it by date and tie against a mid-month balance if the statement prints one.

Overlap with what's already there

The last check isn't about the file at all: find the last date already in that QuickBooks account and drop rows on or before it. Overlap is where most duplicates in For review come from.

Where ZeraBooks fits

ZeraBooks Convert reads the PDF (scans and multi-account PDFs included), splits by account and cardholder, checks each statement against its printed opening and closing balance to the cent, and gives you a QuickBooks-ready CSV in the 3-column layout, one file per account. It doesn't connect to QuickBooks and doesn't make .qbo or IIF files. It's in the ZeraBooks subscription, $79 a month billed annually or $149 monthly, after a 7-day trial.

The non-code walkthrough, with all four ways to get a PDF into QuickBooks Online, is our guide on importing a PDF bank statement into QuickBooks.

Disclosure: I'm part of the ZeraBooks team.

Bank reconciliation as code: deposits in transit, outstanding checks, book errors and one assertion

Damin Mutti — Sat, 24 Oct 2026 02:04:05 +0000

A bank reconciliation in code is: match book lines to bank lines, treat unmatched book deposits as in transit and unmatched book payments as outstanding, treat unmatched bank lines and amount differences as book-side adjustments, then assert that the statement balance adjusted for the first two equals the book balance adjusted for the rest. The book-side items become journal entries.

I'm on the ZeraBooks team. Reconciliation is the core of what our ledger does, and it's often explained as a form to fill in. Written as code it's short, and the structure makes it obvious which side of the reconciliation each item belongs on, which is the part people get wrong by hand.

The two sides

Every reconciling item belongs to exactly one side:

Item	Where it is	Side	Why
Deposit in transit	Books, not bank yet	Bank	The bank will catch up next month
Outstanding check	Books, not bank yet	Bank	Same
Bank fee, interest	Bank, not books	Book	You haven't recorded it; you need to
Amount recorded wrong	Both, different amounts	Book	The bank cleared what was actually written

Bank-side items need no entry; they resolve themselves. Book-side items need a journal entry, or the books stay wrong.

The code

from dataclasses import dataclass
from decimal import Decimal as D

@dataclass(frozen=True)
class Line:
    date: str
    ref: str          # check number or short description
    amount: D         # money in positive, money out negative

def match(book: list[Line], bank: list[Line]):
    """Pair book and bank lines: same check number, else same amount. Each line used once."""
    unmatched_bank = list(bank)
    matched, book_only = [], []
    for b in book:
        cand = [x for x in unmatched_bank if x.ref == b.ref and b.ref.isdigit()] \
            or [x for x in unmatched_bank if x.amount == b.amount and not x.ref.isdigit()]
        if cand:
            matched.append((b, cand[0]))
            unmatched_bank.remove(cand[0])
        else:
            book_only.append(b)
    return matched, book_only, unmatched_bank

def reconcile(book, bank, book_balance: D, statement_balance: D):
    matched, book_only, bank_only = match(book, bank)
    in_transit  = sum((b.amount for b in book_only if b.amount > 0), D("0"))
    outstanding = sum((-b.amount for b in book_only if b.amount < 0), D("0"))
    # matched pairs whose amounts differ are book errors (the bank cleared what was written)
    errors = [(b, k, k.amount - b.amount) for b, k in matched if b.amount != k.amount]
    book_side = sum((k.amount for k in bank_only), D("0")) + sum((e[2] for e in errors), D("0"))

    adj_bank = statement_balance + in_transit - outstanding
    adj_book = book_balance + book_side
    assert adj_bank == adj_book, f"unreconciled difference {adj_bank - adj_book}"
    entries = [(k.ref, k.amount) for k in bank_only] + [(f"correct {b.ref}", diff) for b, _, diff in errors]
    return adj_bank, in_transit, outstanding, entries

Signed amounts throughout: money in positive, money out negative. Decimal, never float.

The matching rule is intentionally simple: checks match on check number, everything else on exact amount, each bank line used once. Matching on check number first is what lets the code detect an amount error on a check: the pair is found by number, and the amounts disagree. Real-world matching needs date windows and handling for split deposits, but the reconciliation logic after matching doesn't change.

A fictional October

Books for a small firm's checking account at October 31 show a balance of 19,826.65. The bank statement's closing balance is 18,962.40.

book = [
    Line("10-03", "2210",    D("-392.00")),
    Line("10-14", "Deposit", D("5200.00")),
    Line("10-20", "2214",    D("-612.00")),
    Line("10-27", "2217",    D("-874.25")),
    Line("10-31", "Deposit", D("2350.00")),
]
bank = [
    Line("10-06", "2210",        D("-362.00")),
    Line("10-15", "Deposit",     D("5200.00")),
    Line("10-31", "Service fee", D("-35.00")),
    Line("10-31", "Interest",    D("4.50")),
]

reconcile(book, bank, D("19826.65"), D("18962.40"))
# (Decimal('19826.15'), Decimal('2350.00'), Decimal('1486.25'),
#  [('Service fee', Decimal('-35.00')), ('Interest', Decimal('4.50')), ('correct 2210', Decimal('30.00'))])

(Only the lines relevant to reconciling items are shown; the month's other matched transactions don't change the result.)

Reading the result

Bank side. The 2,350.00 deposit made on October 31 hasn't reached the bank: in transit. Checks 2214 and 2217, for 612.00 and 874.25, haven't cleared: 1,486.25 outstanding.

18,962.40 plus 2,350.00 minus 1,486.25 is 19,826.15.

Book side. The bank charged a 35.00 service fee and paid 4.50 of interest, neither recorded yet. And check 2210 was written for 362.00 but entered in the books as 392.00; the bank cleared 362.00, so the books understate cash by 30.00.

19,826.65 minus 35.00 plus 4.50 plus 30.00 is 19,826.15.

Both sides land on 19,826.15. The assertion passes, and the function returns three journal entries to post: bank fees 35.00, interest income 4.50, and a 30.00 correction to whatever check 2210 was charged to.

Why the assertion matters

If the assertion fails, the difference is real and unexplained. Common causes, roughly in order:

A transaction that's in the books twice. The difference equals that amount.
A transposition, such as 874.25 entered as 847.25. The difference is divisible by 9 (27.00 here).
Last month's reconciliation wasn't actually finished, so an old outstanding item is missing from this month's list.
A bank line matched to the wrong book line by amount, when two transactions share an amount.

Never "fix" a failed reconciliation by posting the difference to a suspense or miscellaneous account. That makes the assertion pass and hides the problem.

One thing to add before using this

Carry forward outstanding items. A check outstanding at September 30 that clears in October appears on October's bank statement with no October book line. As written, the code would treat it as a bank-only item and propose an entry, which would double-count it. Seed book with last month's outstanding and in-transit items to fix that.

How ZeraBooks does it

ZeraBooks is an AI-native general ledger. It reads your bank and card statements, matches them to the books and proves each month against the statement's printed opening and closing balance: the statement must add up, follow the previous statement and agree with the ledger before a month closes. The AI never does the arithmetic; balances are computed in code. Proposed entries like the three above are approved by a person and can be undone. There's no live bank feed; statements are uploaded as PDF or CSV. It's $79 a month billed annually or $149 monthly, with a 7-day trial.

The step-by-step version without code, with a worked month, is our guide on how to do a bank reconciliation.

Disclosure: I work at ZeraBooks.

Wells Fargo statements: using the half-empty 'Ending daily balance' column as a free parser test

Damin Mutti — Sat, 24 Oct 2026 00:05:06 +0000

Wells Fargo statements print an ending daily balance only on the last transaction of each day, leaving the column blank on other rows. That half-empty column is a free test for a parser: group rows by date, add each day's amounts to a running total, and compare with the printed balance.

A mismatch tells you which day lost or mangled a row, not just that the month is off.

I'm on the ZeraBooks team, where we convert a lot of these. The usual advice is "check that the month ties to the ending balance," which is right but coarse: a month that's off by 425.00 could be off anywhere in 30 days. The daily balance narrows it to one day, and it's sitting in the statement already.

The layout

A Wells Fargo business checking statement typically prints one transaction table with columns for date, check number, description, deposits or credits, withdrawals or debits, and ending daily balance. Credits and debits are separate unsigned columns, and the balance column is filled only on a day's last row. Dates print as month and day; the year comes from the statement period.

Assume your PDF extraction produces this (fictional) October 2026, opening balance 6,215.40, ending balance 7,548.83:

Date,Check Number,Description,Deposits/Credits,Withdrawals/Debits,Ending daily balance
10/1,,Square deposit,1240.00,,7455.40
10/2,1188,Check,,425.00,
10/2,,Gusto payroll ACH,,2880.15,4150.25
10/6,,Mobile deposit,3600.00,,
10/6,,Purchase Home Depot,,186.42,7563.83
10/9,,Wire transfer fee,,15.00,7548.83

Two rows on October 2 and two on October 6 share one balance each. That's the whole point.

The checker

import pandas as pd
from decimal import Decimal

def dec(x):
    return Decimal(str(x)) if pd.notna(x) and str(x).strip() != "" else Decimal("0")

def load(path: str, year: int) -> pd.DataFrame:
    df = pd.read_csv(path, dtype=str, keep_default_na=False)
    df["Date"] = pd.to_datetime(df["Date"] + f"/{year}", format="%m/%d/%Y")
    df["Amount"] = [dec(c) - dec(w) for c, w in zip(df["Deposits/Credits"], df["Withdrawals/Debits"])]
    df["Printed"] = [dec(b) if b.strip() else None for b in df["Ending daily balance"]]
    return df

def check_days(df: pd.DataFrame, opening: Decimal) -> list[str]:
    problems, running = [], opening
    for day, g in df.groupby("Date", sort=True):
        running += sum(g["Amount"], Decimal("0"))
        printed = [p for p in g["Printed"] if p is not None]
        if len(printed) != 1 or g["Printed"].iloc[-1] is None:
            problems.append(f"{day:%Y-%m-%d}: no single ending daily balance on the last row; a row was dropped or split")
            continue
        if running != printed[0]:
            problems.append(f"{day:%Y-%m-%d}: rows give {running}, statement prints {printed[0]}, "
                            f"off by {printed[0] - running}")
            running = printed[0]  # re-anchor so one error doesn't cascade
    return problems

def check_month(df: pd.DataFrame, opening: Decimal, closing: Decimal) -> None:
    total = opening + sum(df["Amount"], Decimal("0"))
    assert total == closing, f"month: {total} != {closing}"

Amounts and balances are read as strings and converted to Decimal, so nothing passes through a float. Two details matter:

The balance must be on the last row of the day. If a day has a balance in the middle and none at the end, rows were reordered or a row was split across lines during extraction. That's flagged separately.
Re-anchoring after a mismatch. Once a day fails, the running total resets to the printed balance. Without that, one dropped row would make every later day fail too, and you'd lose the localization you came for.

Running it

On the clean file:

df = load("wf.csv", 2026)
check_days(df, Decimal("6215.40"))                      # []
check_month(df, Decimal("6215.40"), Decimal("7548.83"))  # passes

Day by day: 6,215.40 plus 1,240.00 is 7,455.40 on October 1. Minus 425.00 and 2,880.15 is 4,150.25 on October 2. Plus 3,600.00 minus 186.42 is 7,563.83 on October 6. Minus 15.00 is 7,548.83 on October 9, the statement's ending balance.

Now simulate the most common extraction failure, a check row that didn't come through because the check number confused the row detection:

check_days(df.drop(index=1), Decimal("6215.40"))
# ['2026-10-02: rows give 4575.25, statement prints 4150.25, off by -425.00']

One line, one day, one amount. Go to October 2 in the PDF and look for a 425.00 debit.

A dropped row that carried the balance looks different:

check_days(df.drop(index=4), Decimal("6215.40"))
# ['2026-10-06: no single ending daily balance on the last row; a row was dropped or split',
#  '2026-10-09: rows give 7735.25, statement prints 7548.83, off by -186.42']

October 6 has no balance on its last remaining row, which is flagged, and since the running total couldn't be re-anchored there, the 186.42 shows up at the next printed balance. Still two adjacent days to look at instead of a whole month.

Other things this catches

Credit and debit columns swapped on a page where the header was misread. Every day on that page fails by twice the day's net.
A row duplicated across a page break, which happens when a table continues onto the next page with a repeated last line. The day fails by exactly that row's amount.
The wrong year on a January statement won't fail this check, because the order of days is unchanged. That needs a separate date-range check against the statement period.

Limits

This relies on the statement printing a daily balance. Many banks don't, and some print one on every row (easy) or never (you're back to the monthly check). Check-image pages at the back of the PDF aren't transactions and shouldn't be parsed into this table. And it can't catch two errors on the same day that cancel out; the deposit count in the statement summary can, if you check it.

Where ZeraBooks Convert fits

ZeraBooks Convert reads Wells Fargo and other bank and card statement PDFs, merges credits and debits into one signed Amount column and proves each statement against its printed balances to the cent, flagging any that don't tie. You download Excel or CSV, including QuickBooks-ready and Xero-ready layouts. It doesn't connect to Wells Fargo or ask for your sign-in. It's part of the ZeraBooks subscription at $79 a month billed annually or $149 monthly, 1,000 pages a month, after a 7-day trial.

Download steps and a converted sample month are in our guide to converting a Wells Fargo bank statement to Excel.

Disclosure: I work at ZeraBooks.

A sales tax payable tie-out in 50 lines of Python, for more than one jurisdiction

Damin Mutti — Fri, 23 Oct 2026 22:02:58 +0000

A sales tax tie-out needs three checks per jurisdiction per month: each opening payable equals the prior closing, opening plus collected minus remitted equals the ledger's closing payable to the cent, and tax collected is within a small tolerance of taxable sales times that jurisdiction's rate. The first two are exact.

The third is a reasonableness test, and its gap divided by the rate points to the sales to review.

I'm on the ZeraBooks team. We published a single-rate version of this as an open example this week. The obvious next question was what happens with two states, so this is the multi-jurisdiction version, with Decimal throughout and a hint for the most common failure.

The input

One row per jurisdiction per month. Remittances come from the bank statement (what was actually paid). Closing payable comes from the ledger. Keeping those two sources separate is what lets the roll-forward catch anything.

Jurisdiction,Month,Taxable sales,Rate,Opening payable,Collected,Remitted per bank,Closing payable per ledger
State A,2026-04,41200.00,0.0725,2610.40,2987.00,2610.40,2987.00
State A,2026-05,38650.00,0.0725,2987.00,2802.13,2987.00,2802.13
State A,2026-06,44120.00,0.0725,2802.13,3194.20,2802.13,3194.20
State B,2026-05,11500.00,0.0600,655.20,690.00,655.20,690.00
State B,2026-06,12400.00,0.0600,690.00,744.00,690.00,744.00
State B,2026-07,13510.00,0.0600,744.00,810.60,744.00,1554.60

All figures are fictional. State A is the original single-rate example. State B is new, and its July has a deliberate error.

The checker

import csv, sys
from collections import defaultdict
from decimal import Decimal, ROUND_HALF_UP

CENT = Decimal("0.01")

def d(s: str) -> Decimal:
    return Decimal(s.replace(",", ""))

def check(path: str, tolerance: Decimal = Decimal("1.00")) -> list[str]:
    rows = defaultdict(list)
    with open(path, newline="") as f:
        for r in csv.DictReader(f):
            rows[r["Jurisdiction"]].append(r)

    problems = []
    for juris, months in rows.items():
        months.sort(key=lambda r: r["Month"])
        prior_close = None
        for r in months:
            m = f'{juris} {r["Month"]}'
            opening, collected = d(r["Opening payable"]), d(r["Collected"])
            remitted, closing = d(r["Remitted per bank"]), d(r["Closing payable per ledger"])

            # 1. continuity: this opening is last month's closing
            if prior_close is not None and opening != prior_close:
                problems.append(f"{m}: opens at {opening}, prior month closed at {prior_close}")

            # 2. roll-forward, to the cent
            expected = opening + collected - remitted
            if expected != closing:
                diff = closing - expected
                hint = " (equals the remittance: booked to an expense?)" if diff == remitted else ""
                problems.append(f"{m}: closing {closing}, roll-forward gives {expected}, off by {diff}{hint}")

            # 3. reasonableness: collected vs sales x rate
            rate = d(r["Rate"])
            should = (d(r["Taxable sales"]) * rate).quantize(CENT, ROUND_HALF_UP)
            gap = collected - should
            if abs(gap) > tolerance:
                implied = (gap / rate).quantize(CENT, ROUND_HALF_UP)
                problems.append(f"{m}: collected {collected}, expected {should}; gap {gap} is about {implied} of sales")
            prior_close = closing
    return problems

if __name__ == "__main__":
    tol = Decimal(sys.argv[2]) if len(sys.argv) > 2 else Decimal("1.00")
    for p in check(sys.argv[1], tol) or ["all months tie"]:
        print(p)

Standard library only. Run it as python3 check.py sales-tax.csv, with an optional tolerance as the second argument.

The output

State A 2026-06: collected 3194.20, expected 3198.70; gap -4.50 is about -62.07 of sales
State B 2026-07: closing 1554.60, roll-forward gives 810.60, off by 744.00 (equals the remittance: booked to an expense?)

Two different kinds of problem, and the checker distinguishes them.

State A, June: a reasonableness gap

The roll-forward ties: 2,802.13 plus 3,194.20 minus 2,802.13 is 3,194.20, matching the ledger. But taxable sales of 44,120.00 at 7.25% should have produced 3,198.70. The ledger collected 4.50 less. Dividing 4.50 by 0.0725 says roughly 62.07 of sales were taxed wrong or marked non-taxable.

The fix belongs in the invoices, not in the payable. Typical causes: an item flagged non-taxable by mistake, tax rounded per line instead of per invoice, a discount applied after tax.

State B, July: a roll-forward break

June closed at 744.00. July collected 810.60, which is exactly 13,510.00 times 6%, and the bank shows 744.00 paid to State B. So the payable should close at 744.00 plus 810.60 minus 744.00, which is 810.60. The ledger says 1,554.60.

The difference is 744.00, the same as the remittance. That's the signature of a payment posted to an expense account ("Taxes and licenses" is the usual one) instead of against the payable. The liability grows by every remittance, and profit is understated by the same amount. The hint in the output is just that equality check, but it identifies this case most of the time.

Choosing the tolerance

I use 1.00 by default. Per-line rounding on a busy month can legitimately produce a few cents of difference, and a tolerance of zero would flag every month. With a 5.00 tolerance the State A gap disappears, which may be fine for your purposes or may hide 62 dollars of mis-taxed sales. Pick it on purpose and write it down.

A better long-term approach is a tolerance proportional to invoice count, say half a cent per invoice, since that's the maximum per-invoice rounding error. That needs invoice counts in the input, which most sales tax reports include.

What the script deliberately doesn't do

Mixed rates within one jurisdiction. A state with county and city add-ons needs one row per rate, or the rate column needs to be an effective rate you computed elsewhere. The script assumes the rate in the file is correct.
Filing periods that aren't monthly. Quarterly filers can still check monthly, but the remittance lands once a quarter, so most months will show zero remitted and a growing payable. That's correct.
Marketplace sales. Where a marketplace collects and remits the tax, those sales shouldn't be in your taxable sales column at all.
Canada. GST/HST works as collected minus input tax credits rather than collected minus remitted alone. The same structure works with an extra column for credits.

Where this sits in a close

Sales tax payable is one account in a balance sheet reconciliation, where every asset and liability is matched to an outside document: bank and card accounts to statements, payroll liabilities to the payroll register, loans to lender statements, sales tax to the return. Cash goes first, because a remittance that cleared on the wrong date shows up there before it confuses this check.

ZeraBooks is an AI-native general ledger that does the bank and card part: it reads statements, categorizes, and proves every month against each statement's printed opening and closing balance. The AI never does the arithmetic. Entries are approved by a person and reversible. There's no live bank feed; statements are uploaded. It's $79 a month billed annually or $149 monthly, with a 7-day trial.

The full method for every account type, with a worked month, is our guide to balance sheet reconciliation.

Disclosure: I work at ZeraBooks.

Parsing RBC and TD chequing statements in Python: year-less dates, header-mapped columns and a balance proof

Damin Mutti — Fri, 23 Oct 2026 20:45:46 +0000

To parse RBC and TD business chequing statements, map the debit and credit columns by header name, because the two banks order them differently. Take each row's year from the statement period, not the row. Merge the two amount columns into one signed Amount. Then assert, with Decimal, that the opening balance plus the sum equals the printed closing balance.

I'm on the ZeraBooks team, and we've just published both layouts with a fictional sample month each as open reference data. This post is the code side: what a Canadian statement parser has to do that a U.S.-tuned one often doesn't.

The problem in one table

Quirk	Why it breaks naive parsers
Dates print as day and month, no year	A January statement starting with a late-December row gets the wrong year
Separate debit and credit columns, no minus signs	Read the wrong column and a cheque becomes a deposit
RBC and TD order columns differently	Position-based templates swap amounts and dates
Running balance often only on a day's last row	Can't check every row, only day ends and the close

I'll assume the PDF text extraction is done and you have each table row as a dict keyed by the printed header. That's the hard part, but it's library-specific; everything after it is not.

Map columns by header

Headers vary in wording between account types and years, so normalize them against a small synonym table:

import re

HEADER_MAP = {
    "date": "date",
    "description": "description",
    "cheques & debits": "debit",
    "cheques and debits": "debit",
    "withdrawals": "debit",
    "cheque/debit": "debit",
    "deposits & credits": "credit",
    "deposits and credits": "credit",
    "deposits": "credit",
    "deposit/credit": "credit",
    "balance": "balance",
}

def normalize_header(h: str) -> str:
    key = re.sub(r"\s+", " ", h.replace("($)", "")).strip().lower()
    if key not in HEADER_MAP:
        raise KeyError(f"unknown column header: {h!r}")
    return HEADER_MAP[key]

Raising on an unknown header is deliberate. Silently guessing is how a "Withdrawals" column ends up as credits.

When it raises, add the new spelling to the table after looking at a real statement. Over time the table becomes a record of every header variant you've seen, which is more useful than a fuzzy matcher that is right most of the time and silently wrong the rest. Keep the raw header in your logs too, so a support question about a strange file can be answered without the PDF.

Give each row a year

The statement header prints the period, for example December 15, 2025 to January 14, 2026. A row reading "29 Dec" belongs to 2025 and "03 Jan" to 2026. The rule: try the period's end year; if that date falls after the period end, use the start year.

from datetime import date, datetime

MONTHS = {m: i for i, m in enumerate(
    ["jan","feb","mar","apr","may","jun","jul","aug","sep","oct","nov","dec"], 1)}

def parse_day_month(s: str) -> tuple[int, int]:
    s = s.strip().lower().replace(".", "")
    m = re.fullmatch(r"(\d{1,2})\s*([a-z]{3})", s) or re.fullmatch(r"([a-z]{3})\s*(\d{1,2})", s)
    if not m:
        raise ValueError(f"unparseable date: {s!r}")
    a, b = m.groups()
    day, mon = (int(a), b) if a.isdigit() else (int(b), a)
    return day, MONTHS[mon]

def with_year(s: str, start: date, end: date) -> date:
    day, month = parse_day_month(s)
    d = date(end.year, month, day)
    if d > end:
        d = date(start.year, month, day)
    if not (start <= d <= end):
        raise ValueError(f"{s} falls outside {start}..{end}")
    return d

It accepts "05 Aug" and "AUG05" because the exact text differs by bank and format. The range check at the end catches a row from the wrong statement that slipped into the batch.

Merge to one signed Amount

from decimal import Decimal

def money(s: str | None) -> Decimal:
    if not s or not s.strip():
        return Decimal("0")
    return Decimal(s.replace(",", "").replace("$", "").strip())

def to_rows(raw_rows, start, end):
    out = []
    for r in raw_rows:
        r = {normalize_header(k): v for k, v in r.items()}
        debit, credit = money(r.get("debit")), money(r.get("credit"))
        if debit and credit:
            raise ValueError(f"both columns filled: {r}")
        out.append({
            "date": with_year(r["date"], start, end),
            "description": " ".join(r["description"].split()),
            "amount": credit - debit,
            "balance": money(r.get("balance")) if r.get("balance") else None,
        })
    return out

A note on money: this assumes English formatting (1,420.50). Some Canadian bank CSV exports in French-language profiles use a comma as the decimal separator. If you handle those, detect the locale per file rather than guessing per value.

The proof

The Cedar Row Landscaping sample (RBC, August 2026, fictional) has an opening balance of 8,240.19 and a printed closing balance of 10,742.35:

rows = [
    {"date": date(2026,8,5),  "description": "Deposit - Customer payment 2204", "amount": Decimal("3850.00")},
    {"date": date(2026,8,12), "description": "Cheque 118",                      "amount": Decimal("-1420.50")},
    {"date": date(2026,8,14), "description": "PAD - Fleet fuel card",           "amount": Decimal("-612.34")},
    {"date": date(2026,8,20), "description": "Interac e-Transfer received",     "amount": Decimal("975.00")},
    {"date": date(2026,8,27), "description": "Monthly fee",                     "amount": Decimal("-6.00")},
    {"date": date(2026,8,31), "description": "PAD - Commercial insurance",      "amount": Decimal("-284.00")},
]

opening, closing = Decimal("8240.19"), Decimal("10742.35")
assert opening + sum(r["amount"] for r in rows) == closing

8,240.19 plus 3,850.00, minus 1,420.50, minus 612.34, plus 975.00, minus 6.00, minus 284.00 is 10,742.35. The TD sample (Maple Harbour Cleaning) goes from 3,105.60 to 5,883.12 the same way.

Use the half-filled balance column too

Where the statement prints a balance, check it:

running = opening
for r in rows:
    running += r["amount"]
    if r.get("balance") is not None:
        assert running == r["balance"], f"{r['date']}: {running} != {r['balance']}"

Because the balance often appears only on a day's last row, this localizes an error to a single day instead of the whole month.

The rows that go missing

In practice the rows dropped most often are the small fee lines at month end (6.00 here, 4.95 on the TD sample), because they sit near the footer with no payee. The closing-balance assertion catches them. Keep cheque numbers in the description so they can be matched to a cheque register later.

Where ZeraBooks Convert fits

If you'd rather not maintain this per bank, ZeraBooks Convert reads bank and credit card statement PDFs, including scans, proves every statement against its printed opening and closing balance to the cent, and flags any that don't tie. Output is Excel or CSV, including QuickBooks-ready and Xero-ready layouts. It doesn't connect to banks. It's in the ZeraBooks subscription at $79 a month billed annually or $149 monthly, 1,000 pages a month, after a 7-day trial.

The non-code overview, for any bank and card, is our guide to the bank statement converter.

Disclosure: I work at ZeraBooks.

Bank statement analysis in pandas: netting out own-account transfers before you average deposits

Damin Mutti — Thu, 22 Oct 2026 20:18:45 +0000

To analyze bank statements correctly in pandas, load every account the borrower owns into one frame with an Account column, pair each outflow in one account with the matching inflow in another, drop those pairs from the deposit totals, and only then compute monthly averages, NSF counts and balances. Skip the pairing and deposits are overstated. ZeraBooks Convert produces the input file, checked against each statement's printed balances.

I'm on the ZeraBooks team. We don't do the analysis itself; our converter turns statement PDFs into a spreadsheet and proves each one. The step that's easiest to skip after conversion is the transfer pairing, so this post is the code for it.

The input

Convert can download several statements together as one file with an Account column. Assume a CSV like this:

Account,Date,Description,Type,Amount
Checking ...2214,2026-07-03,ONLINE TRANSFER FROM SAV ...8830,Transfer,4000.00
Savings ...8830,2026-07-03,ONLINE TRANSFER TO CHK ...2214,Transfer,-4000.00
Checking ...2214,2026-07-05,DEPOSIT CLIENT 1187,Deposit,6200.00
Checking ...2214,2026-08-14,NSF RETURNED ITEM FEE,Fee,-35.00
...

Amounts are signed: money in positive, money out negative. Type comes from the section the statement printed the line under, which helps but isn't enough on its own. Plenty of banks print an incoming transfer as a plain deposit.

import pandas as pd

df = pd.read_csv("statements.csv", parse_dates=["Date"], dtype={"Amount": "float64"})
df["Amount"] = df["Amount"].round(2)
df["Month"] = df["Date"].dt.to_period("M")

For anything you'll hand to a lender I'd use Decimal, but cents-rounded floats are fine for exploration.

Pairing transfers across accounts

A transfer between two of the borrower's own accounts shows up twice: negative in one account, positive in the other, same amount, within a day or two. The pairing below is greedy and conservative: exact amount, different account, opposite sign, dates within a window.

def pair_transfers(df: pd.DataFrame, window_days: int = 3) -> pd.DataFrame:
    df = df.copy()
    df["pair_id"] = pd.NA
    outs = df[df["Amount"] < 0].sort_values("Date")
    ins = df[df["Amount"] > 0]
    used = set()
    pid = 0
    for i, o in outs.iterrows():
        cands = ins[
            (ins["Amount"] == -o["Amount"])
            & (ins["Account"] != o["Account"])
            & ((ins["Date"] - o["Date"]).abs().dt.days <= window_days)
            & (~ins.index.isin(used))
        ]
        if len(cands):
            j = (cands["Date"] - o["Date"]).abs().idxmin()
            df.loc[[i, j], "pair_id"] = pid
            used.add(j)
            pid += 1
    return df

df = pair_transfers(df)

It's O(n√óm), which is fine for a few thousand rows. Two things it deliberately does not do: match on description text, which varies wildly between banks, and match partial amounts. A 4,000.00 outflow and a 3,999.00 inflow aren't a pair; that's a question for the borrower.

What about transfers from an account you don't have statements for, like a personal account? They won't pair. Flag inflows whose description looks like a transfer and send them to a human:

looks_like_transfer = df["Description"].str.contains(
    r"TRANSFER|XFER|FROM SAV|FROM CHK", case=False, regex=True)
unpaired_suspects = df[looks_like_transfer & df["pair_id"].isna() & (df["Amount"] > 0)]

The summary

Now restrict to the operating account and compute what an underwriter asks for:

op = df[df["Account"] == "Checking ...2214"]

summary = op.groupby("Month").agg(
    all_deposits=("Amount", lambda s: s[s > 0].sum()),
    withdrawals=("Amount", lambda s: -s[s < 0].sum()),
)
summary["own_transfers_in"] = (
    op[(op["Amount"] > 0) & op["pair_id"].notna()].groupby("Month")["Amount"].sum()
).reindex(summary.index, fill_value=0)
summary["business_deposits"] = summary["all_deposits"] - summary["own_transfers_in"]

nsf = op["Description"].str.contains(r"NSF|RETURNED ITEM|OVERDRAFT", case=False)
summary["nsf_items"] = op[nsf].groupby("Month").size().reindex(summary.index, fill_value=0)

With a fictional catering company's July to September 2026 checking statements, that produces:

Month	All deposits	Own transfers in	Business deposits	Withdrawals	NSF
2026-07	30,500.00	4,000.00	26,500.00	28,900.00	0
2026-08	26,200.00	0.00	26,200.00	31,050.00	1
2026-09	35,400.00	6,500.00	28,900.00	33,275.50	0

Average business deposits: 81,600.00 / 3 = 27,200.00. Average of all deposits: 92,100.00 / 3 = 30,700.00. That 3,500.00 a month gap is the whole reason for the pairing step.

Balances: take them from the statement

Don't compute month-end balances from a cumulative sum of transactions and call it done. Take the printed closing balance from each statement and use the cumulative sum as a check:

opening = 12000.00
closing_printed = {"2026-07": 13600.00, "2026-08": 8750.00, "2026-09": 10874.50}

running = opening
for m, row in summary.iterrows():
    running = round(running + row["all_deposits"] - row["withdrawals"], 2)
    assert running == closing_printed[str(m)], f"{m}: computed {running}"

12,000.00 + 30,500.00 ‚àí 28,900.00 = 13,600.00, then 8,750.00, then 10,874.50. If an assertion fails, a page or a line is missing from the input and every figure above it is suspect.

Lowest daily balance is a different story. You can't reconstruct it reliably from transactions alone if the statement has same-day ordering you don't know; read it from the statement's daily balance section.

Where the input comes from

ZeraBooks Convert turns bank and card statement PDFs, scans included, into rows, checks each statement against its printed opening and closing balance to the cent, and lets you download many statements at once with an Account column or a tab per account. It doesn't score applicants or flag NSFs; the analysis is yours. It's in the ZeraBooks subscription at $79 a month billed annually or $149 monthly, after a 7-day trial.

The non-code version, with what lenders, family law teams and auditors each look for, is our guide to bank statement analysis.

Disclosure: I work at ZeraBooks.

Proving a parsed brokerage statement: the cash check and the position check in Python

Damin Mutti — Thu, 22 Oct 2026 17:12:14 +0000

To prove a parsed brokerage statement, run two checks. First, opening cash plus every signed activity row must equal the closing cash the statement prints. Second, quantity times price must equal market value for every position. If both pass to the cent, the parse is whole. This is the same idea ZeraBooks Convert uses before it hands anyone a spreadsheet.

I work on ZeraBooks, and brokerage statements are the most annoying document type we read. A bank statement is basically one table. A brokerage statement is a summary, a holdings table, an activity table and an income summary, in whatever order and wording the broker likes, sometimes repeated per account in one PDF. Parsing it is half the job. Knowing whether you parsed it correctly is the other half, and it's the half people skip.

This post is about that second half. The code is plain Python with decimal, no dependencies.

The data model

After extraction, a monthly statement for one account reduces to a few things:

from dataclasses import dataclass
from decimal import Decimal
from typing import Literal

Kind = Literal["Deposit", "Withdrawal", "Buy", "Sell", "Dividend",
               "Interest", "Reinvest", "Fee", "Transfer"]

@dataclass(frozen=True)
class Activity:
    date: str           # as printed in the activity section
    description: str
    kind: Kind
    amount: Decimal     # signed by cash direction: in > 0, out < 0

@dataclass(frozen=True)
class Position:
    symbol: str
    quantity: Decimal
    price: Decimal
    market_value: Decimal   # as printed, not computed

@dataclass(frozen=True)
class Statement:
    account: str
    opening_cash: Decimal
    closing_cash: Decimal   # as printed
    activity: list[Activity]
    positions: list[Position]

Two design choices matter here.

amount is signed by cash direction, not by "type". A buy is negative because cash left. Reinvestments come through as a pair: a Dividend that's positive and a Reinvest that's negative, same date, same amount. Collapsing them into one zero row is the most common way a brokerage spreadsheet loses income.

market_value and closing_cash are stored as printed. Never compute them and then compare a value to itself.

Check 1: the cash proof

def cash_proof(s: Statement) -> Decimal:
    """Returns the difference; zero means the activity is complete."""
    computed = s.opening_cash + sum((a.amount for a in s.activity), Decimal("0"))
    return computed - s.closing_cash

A fictional October 2026 for a taxable account. Opening cash 3,400.00, closing cash printed as 1,743.27.

from decimal import Decimal as D

oct_2026 = Statement(
    account="Individual ...7731",
    opening_cash=D("3400.00"),
    closing_cash=D("1743.27"),
    activity=[
        Activity("10/01/2026", "Electronic deposit", "Deposit", D("1000.00")),
        Activity("10/02/2026", "Bought 25 shares, total market fund", "Buy", D("-3912.40")),
        Activity("10/15/2026", "Cash dividend", "Dividend", D("27.55")),
        Activity("10/20/2026", "Sold 40 shares, bond fund", "Sell", D("1240.00")),
        Activity("10/31/2026", "Interest on cash", "Interest", D("3.12")),
        Activity("10/31/2026", "Advisory fee", "Fee", D("-15.00")),
    ],
    positions=[
        Position("TMKT", D("25"), D("118.42"), D("2960.50")),
        Position("INTL", D("40"), D("51.07"), D("2042.80")),
    ],
)

assert cash_proof(oct_2026) == 0

3,400.00 + 1,000.00 ‚àí 3,912.40 + 27.55 + 1,240.00 + 3.12 ‚àí 15.00 = 1,743.27. The difference is zero, so every activity row is present and signed correctly.

When it isn't zero, the size of the gap is a clue:

def diagnose(diff: Decimal, rows: list[Activity]) -> list[str]:
    hints = []
    for r in rows:
        if abs(r.amount) == abs(diff):
            hints.append(f"row {r.date} {r.description}: missing or doubled?")
        if abs(r.amount) * 2 == abs(diff):
            hints.append(f"row {r.date} {r.description}: sign flipped?")
    if diff != 0 and (diff * 100) % 9 == 0:
        hints.append("gap divisible by 9 in cents: transposed digits?")
    return hints

A dropped Reinvest row leaves you over by exactly the dividend. A sign flip leaves you off by twice the row.

Check 2: positions

def position_errors(s: Statement, tolerance=D("0.01")) -> list[str]:
    errs = []
    for p in s.positions:
        computed = (p.quantity * p.price).quantize(D("0.01"))
        if abs(computed - p.market_value) > tolerance:
            errs.append(f"{p.symbol}: {p.quantity} x {p.price} = {computed}, "
                        f"printed {p.market_value}")
    return errs

assert position_errors(oct_2026) == []

25 √ó 118.42 = 2,960.50 and 40 √ó 51.07 = 2,042.80. Both match. The one-cent tolerance exists because some brokers print a rounded price while computing value from an unrounded one. Anything bigger is usually a misread digit in quantity or price.

What these checks don't tell you

They don't give you gains. A sell row is proceeds, and the gain needs cost basis, which lives on the broker's tax documents, not the monthly statement. Don't try to derive it from a year of statements; lots, wash sales and corporate actions will get you.

They also don't catch a row that's present but in the wrong kind. A dividend tagged as interest still proves. For that, compare your dividend and interest totals for the year against the broker's income summary and tax form.

Where this lives in ZeraBooks

ZeraBooks Convert reads brokerage and retirement statements from any broker (PDFs up to 50 MB) into Summary, Holdings and Activity sheets, and checks cash and values against the statement to the cent before you download. It isn't a cost-basis calculator. It's part of the ZeraBooks subscription, $79 a month billed annually or $149 monthly, after a 7-day trial.

If you want the accounting side of this (which statement sections become rows, and how to use twelve months of them at tax time), we wrote that up as a guide to converting a brokerage statement to Excel.

Disclosure: I'm on the ZeraBooks team.

A break-even model for bookkeeping costs: when does a hire beat a freelancer?

Damin Mutti — Sun, 18 Oct 2026 06:25:34 +0000

Under the assumptions below, a full-time bookkeeper costs about $5,212 a month, and a $45-an-hour freelancer costs the same at about 116 hours a month. At 2.7 minutes of hand work per statement line, that is about 2,600 lines a month. Below that, paying for hours is cheaper. Above it, salary starts to win.

Writing it as code makes every input a knob. Change the rate, the minutes per line or the benefits, and the break-even moves. I work on ZeraBooks, and owners ask this often enough that it was worth making explicit.

Where do the bookkeeping cost inputs come from?

const BLS_MEDIAN_HOURLY = 24.36;   // BLS, May 2025, bookkeeping clerks
const BLS_MEDIAN_YEARLY = 50670;   // same source
const EMPLOYER_FICA = 0.0765;      // 6.2% Social Security + 1.45% Medicare
const BENEFITS_YEARLY = 8000;      // assumption, not data
const FREELANCE_HOURLY = 45;       // assumption, not data
const HOURS_PER_LINE = 8 / 180;    // assumption: 8 hours for 180 lines

The last line is the one people argue about. Eight hours for 180 lines is about 2.7 minutes a line, covering categorizing and reconciling by hand. A messy month takes longer, a clean month with recurring vendors less. Treat it as a starting point and measure your own.

Full time is the only option whose cost doesn't move with volume. That is the whole problem with it for a small business.

How do you model monthly bookkeeping cost by volume?

type Option = { name: string; monthly: number };

const FULL_TIME = (BLS_MEDIAN_YEARLY * (1 + EMPLOYER_FICA) + BENEFITS_YEARLY) / 12;
const round = (n: number) => Math.round(n * 100) / 100;

function monthlyCosts(lines: number): Option[] {
  const hours = lines * HOURS_PER_LINE;
  return [
    { name: "full-time", monthly: round(FULL_TIME) },
    { name: "part-time", monthly: round(hours * BLS_MEDIAN_HOURLY * (1 + EMPLOYER_FICA)) },
    { name: "freelance", monthly: round(hours * FREELANCE_HOURLY) },
  ];
}

function breakEvenLines(): number {
  return Math.ceil(FULL_TIME / FREELANCE_HOURLY / HOURS_PER_LINE);
}

Where is the break-even point?

Lines a month	Hours	Part-time employee	Freelancer	Full-time
180	8.0	209.79	360.00	5,212.19
450	20.0	524.47	900.00	5,212.19
1,500	66.7	1,748.24	3,000.00	5,212.19
2,600	115.6	3,030.28	5,200.00	5,212.19

breakEvenLines() returns 2,607: the first whole line count where the freelancer's bill passes the salary.

The output a monthly service delivers instead of hours: a read-only dashboard for a closed month.

What does the bookkeeping cost model leave out?

Plenty, and it is worth being honest about it.

Part-time looks cheapest at every volume because it carries no benefits. In practice, finding a reliable person for 8 hours a month is hard, and turnover resets the learning curve.
Payroll and inventory add work that isn't proportional to statement lines. Twice-monthly payroll adds a fixed chunk to every period.
Catch-up is a one-time cost on top of any option. Six months behind means the first quote includes that.
A monthly service isn't in the table, because its price is quoted rather than computed. Price your own line count here, then compare with the fixed quotes you get.

How should you use the model?

Count last month's lines across every bank and card statement, plug in your local freelance rate, and see which side of the break-even you sit on. Most small businesses land far below it.

const myLines = 320;
console.table(monthlyCosts(myLines));

The page this model comes from walks through the same numbers in plain English, with the BLS wage table and what pushes the price up: how much a bookkeeper costs, priced four ways.

Key takeaways

Full-time at the BLS median plus 7.65% and $8,000 of benefits: $5,212.19 a month.
Break-even with a $45/hour freelancer: 2,607 lines a month at 8 hours per 180 lines.
Every input is an assumption you should replace with your own.
Fixed monthly services are quoted, so compare them against your computed hourly figure.

FAQ

What does a bookkeeper earn per hour in the U.S.?

The BLS median was $24.36 an hour in May 2025, or $50,670 a year.

Why does the part-time line look so cheap?

It carries only payroll tax, no benefits, and assumes you can hire someone reliable for 8 hours a month, which is often the hard part.

Is software alone cheaper than a bookkeeper?

In money, yes: ZeraBooks software is $79 a month billed annually or $149 monthly. In time, it depends on you, since you still review and close each month.

Disclosure: I'm on the ZeraBooks team. ZeraBooks bookkeeping services are a fixed monthly fee from $150 in U.S. dollars, quoted after a free call, worked from uploaded statements rather than bank feeds.

The trust account invariant: one bank balance, many owners, and the check that catches commingling

Damin Mutti — Sun, 18 Oct 2026 04:25:47 +0000

A property manager's trust account obeys one invariant: bank balance = every owner's balance + every security deposit held, at every moment. A second rule catches quieter commingling: no single owner's balance may go below zero, because if it does, another owner's money paid that owner's bill. Check both after every posting, not only at month end.

I work on ZeraBooks, and this is the cleanest data model I know for trust money. Below is a Python sketch. All figures are fictional and match the worked month on our property management page.

How do you model a trust account in code?

from collections import defaultdict
from decimal import Decimal as D

class Trust:
    def __init__(self):
        self.bank = D("0")
        self.owner = defaultdict(lambda: D("0"))     # owed to each owner
        self.deposits = defaultdict(lambda: D("0"))  # held for each owner's tenants

    def post(self, owner: str, amount: D, kind: str):
        """amount is signed from the bank's view: + in, - out."""
        self.bank += amount
        if kind == "deposit":
            self.deposits[owner] += amount
        else:
            self.owner[owner] += amount
        self.check(owner)

    def check(self, owner: str):
        held = sum(self.owner.values()) + sum(self.deposits.values())
        assert self.bank == held, f"bank {self.bank} vs held {held}: does not reconcile"
        assert self.owner[owner] >= 0, f"{owner} is negative: another owner's money was used"

The first assertion is the reconciliation. The second is the one most spreadsheets don't have.

What does a clean month in the trust account look like?

Twelve units, three owners, an 8% fee on rent collected. The trust opens May with $9,600 of deposits.

t = Trust()
for owner, amt in [("Maple", "4800"), ("Elm", "3200"), ("Cedar", "1600")]:
    t.post(owner, D(amt), "deposit")                 # opening deposits, 9,600

t.post("Maple", D("8700.00"), "rent")
t.post("Elm",   D("6400.00"), "rent")
t.post("Elm",   D("75.00"),   "late fee")            # owner's under this agreement
t.post("Cedar", D("4200.00"), "rent")
t.post("Cedar", D("2100.00"), "deposit")             # new tenant

for owner, fee in [("Maple", "696.00"), ("Elm", "512.00"), ("Cedar", "336.00")]:
    t.post(owner, -D(fee), "fee to operating")

t.post("Maple", D("-640.00"), "repair")
t.post("Elm",   D("-380.00"), "repair")

for owner, paid in [("Maple", "7364.00"), ("Elm", "5583.00"), ("Cedar", "3864.00")]:
    t.post(owner, -D(paid), "owner payout")

print(t.bank, dict(t.owner), sum(t.deposits.values()))
# 11700.00, every owner balance 0.00, deposits 11700.00

Trust account, May	Maple Court	Elm Street	Cedar Lane	Total
Rent collected	8,700.00	6,400.00	4,200.00	19,300.00
Late fee	0.00	75.00	0.00	75.00
Management fee at 8%	(696.00)	(512.00)	(336.00)	(1,544.00)
Repairs paid	(640.00)	(380.00)	0.00	(1,020.00)
Paid out to owner	(7,364.00)	(5,583.00)	(3,864.00)	(16,811.00)
Owner balance, May 31	0.00	0.00	0.00	0.00

Every post passes both assertions. On May 31 the bank shows $11,700.00, exactly the deposits held.

The bank side of the same idea in ZeraBooks: deposits, withdrawals and net must agree with the statement before a month is signed off.

How does commingling show up in the data?

Run the same month in a different order. Pay the Elm Street plumber on May 2, before Elm's rent has come in:

t = Trust()
# ...opening deposits as above...
t.post("Elm", D("-380.00"), "repair")
# AssertionError: Elm is negative: another owner's money was used

The bank balance is still positive, and the first assertion still holds, because the bank doesn't know whose money is whose. The $380 came out of money that belongs to Maple's owner or Cedar's tenants. In many states, that is what trust account rules prohibit, even if Elm's rent arrives the next day.

A month-end reconciliation can pass even when an owner went negative for two weeks in the middle. Check after every posting.

No code fixes this after the fact. The practice does: pay a repair from trust only when that owner's balance covers it, or have the owner fund a reserve first.

Which design choices keep the model honest?

Keep deposits separate from owner balances. Both are liabilities, but deposits belong to tenants. An owner payout should never reach into the deposit total.
Move fees out of trust as a transfer. The 8% fee is the manager's income only once it has moved to the operating account. In the trust model it is money leaving that owner's balance.
Check after every post. Month-end checks miss mid-month negatives.
Use Decimal for money. The invariant is an equality to the cent, and float sums drift.

Key takeaways

Invariant: trust bank balance = owner balances + deposits held, always.
Second rule: no owner below zero, or another owner's money paid their bill.
In the worked May, $1,544.00 of fees moved to operating and the trust closed at $11,700.00, all deposits.
Assert after every posting; month-end reconciliation alone can hide commingling.

FAQ

Why can the bank balance be fine while trust rules are broken?

Because the bank balance is a total. It can't tell whose money paid a bill. Only per-owner balances show that.

Is a security deposit an owner's money?

No. It is a liability to the tenant until the lease ends, so it is tracked apart from what is owed to the owner.

Does ZeraBooks keep tenant ledgers?

No. ZeraBooks is a general ledger, not property management software. It has no tenant ledgers, rent collection or portals; managers send reports from their property software.

The full month, with the owner statement mapped to Schedule E lines, is in the guide to bookkeeping for property management. Disclosure: I'm on the ZeraBooks team. ZeraBooks bookkeeping services reconcile trust and operating accounts monthly from uploaded statements, from $150 a month in U.S. dollars.

Building a construction WIP schedule in Python: percent complete, over and under billing, and the month-end entry

Damin Mutti — Sun, 18 Oct 2026 02:25:21 +0000

A construction WIP schedule computes earned revenue for each open job as contract price times percent complete, where percent complete is cost to date divided by estimated total cost. Billed minus earned is overbilling when positive and underbilling when negative. One journal entry a month moves the totals into the ledger, and debits must equal credits.

I work on ZeraBooks, and contractors send us exactly this report each month. Here is the computation with the figures from our contractor guide. All jobs are fictional.

What inputs does a WIP schedule need?

from dataclasses import dataclass
from decimal import Decimal as D, ROUND_HALF_UP

@dataclass
class Job:
    name: str
    contract: D        # including approved change orders
    est_cost: D        # the current estimate, not the original bid
    cost_to_date: D
    billed: D

def cents(x: D) -> D:
    return x.quantize(D("0.01"), rounding=ROUND_HALF_UP)

Estimated cost is the current estimate, not the original bid. That one field decides whether the whole schedule is honest.

How do you calculate over and under billing in code?

def wip_row(j: Job) -> dict:
    pct = j.cost_to_date / j.est_cost
    earned = cents(j.contract * pct)
    diff = cents(j.billed - earned)
    return {
        "job": j.name,
        "pct": f"{pct:.2%}",
        "earned": earned,
        "over": diff if diff > 0 else D("0.00"),
        "under": -diff if diff < 0 else D("0.00"),
    }

jobs = [
    Job("Kitchen remodel", D("200000"), D("150000"), D("60000"), D("95000")),
    Job("Office build-out", D("120000"), D("96000"), D("72000"), D("78000")),
]
rows = [wip_row(j) for j in jobs]

Job	Contract	Est. cost	Cost to date	Billed	Percent	Earned	Over	Under
Kitchen remodel	200,000	150,000	60,000	95,000	40.00%	80,000.00	15,000.00	0.00
Office build-out	120,000	96,000	72,000	78,000	75.00%	90,000.00	0.00	12,000.00

What is the month-end WIP journal entry?

Revenue in the ledger has been recorded from progress bills. The WIP entry adjusts it to earned.

def wip_entry(rows: list[dict]) -> list[tuple[str, D, D]]:
    over = sum((r["over"] for r in rows), D("0"))
    under = sum((r["under"] for r in rows), D("0"))
    return [
        ("40100 Contract revenue", over, D("0")),
        ("20300 Billings in excess of costs and estimated earnings", D("0"), over),
        ("11300 Costs and estimated earnings in excess of billings", under, D("0")),
        ("40100 Contract revenue", D("0"), under),
    ]

entry = wip_entry(rows)
assert sum(d for _, d, _ in entry) == sum(c for _, _, c in entry)

Debits equal credits by construction: $27,000.00 each side here. Net, revenue falls by $3,000.00 for the month.

A journal entry in ZeraBooks: it won't save until the difference between debits and credits is 0.00.

Most bookkeepers reverse this entry on the first day of the next month and post a fresh one at the next month end. That keeps the balances equal to the current schedule instead of a running sum of old adjustments.

What happens when the estimate changes?

Say the kitchen's estimate rises to $170,000 after a tile change and an extra week of labor. Nothing else changes.

jobs[0].est_cost = D("170000")
wip_row(jobs[0])
# pct 35.29%, earned 70,588.24, over 24,411.76

Overbilling jumps by $9,411.76, and revenue to date drops by the same amount, in the month the estimate changed. The job didn't get worse this month; the books caught up with it. If estimates are only updated at year end, this whole correction lands in December.

Which guardrails should a WIP script have?

def sanity(j: Job) -> list[str]:
    issues = []
    if j.cost_to_date > j.est_cost:
        issues.append("cost to date exceeds estimate: update the estimate")
    if j.est_cost >= j.contract:
        issues.append("estimated cost at or above contract: expected loss, talk to your accountant")
    return issues

Percent complete above 100% is always an estimate that wasn't updated. An estimated cost above the contract is a losing job, and how that loss is recorded is a call for the contractor's accountant.

Where does the WIP data come from?

Cost to date per job comes from wherever job costing lives: the estimating tool, project software or a spreadsheet. The general ledger carries totals by cost type: labor, materials, subs, equipment, permits. The rest of a contractor's month, including retainage and the chart of accounts, is in the guide to bookkeeping for contractors.

Key takeaways

Percent complete = cost to date / current estimated cost.
Earned = contract x percent. Billed minus earned is over (liability) or under (asset).
One balanced entry per month, reversed on day one of the next month.
Update estimates monthly; a stale estimate makes every report wrong until December.

FAQ

Is overbilling revenue?

No. It is billed but not yet earned, so it sits as a liability (billings in excess of costs and estimated earnings) until the work catches up.

Why reverse the WIP entry every month?

So the balance sheet always shows the current schedule's over and under billing, rather than a sum of every past adjustment.

Does ZeraBooks calculate job costing?

No. ZeraBooks has no job or class tags, so job costing stays in your project tool. Its WIP report feeds the month-end entry.

Disclosure: I'm on the ZeraBooks team. ZeraBooks bookkeeping services take the contractor's WIP report and post this entry monthly, from $150 a month in U.S. dollars, working from uploaded statements and invoices, with no bank feeds.