Grant Accounting's #1 Mistake: Commingling Restricted and Unrestricted Funds—How Does Beancount Prevent This Technically?

General
1

As a CPA who’s seen too many nonprofit audit findings, I need to talk about something that keeps me up at night: restricted vs. unrestricted fund commingling. It’s the #1 grant accounting mistake, and I just had a client face a brutal audit because of it.

The Problem

Last month, I got a call from a nonprofit executive director in tears. Their annual audit flagged $40,000 in commingled funds—restricted grant money from a major foundation had been used to cover unrestricted operating expenses. Even though it was accidental (bookkeeper didn’t understand the restriction), the consequences were severe:

  • Foundation demanded full explanation and corrective action plan
  • Audit opinion was qualified (red flag for future funders)
  • Two board members resigned over “financial mismanagement” concerns
  • They’re now on every funder’s watch list

According to nonprofit accounting experts, even accidental commingling can undermine donor confidence and create audit findings that follow your organization for years. Under ASC 958 and UPMIFA, spending restricted funds outside the donor’s intent violates nonprofit accounting standards.

The Beancount Technical Solution

Here’s where I think Beancount provides an elegant solution through its account hierarchy. Instead of relying on fund codes or class tracking (like QuickBooks), the double-entry system structurally prevents commingling.

Consider this account structure:

Assets:BankAccounts:Checking:Unrestricted
Assets:BankAccounts:Checking:Restricted:GrantFoundationA
Assets:BankAccounts:Checking:Restricted:GrantFoundationB
Expenses:Programs:Unrestricted
Expenses:Programs:Restricted:GrantFoundationA
Expenses:Programs:Restricted:GrantFoundationB

Now, when you record a transaction:

2026-03-15 * "Program supplies purchased with Foundation A grant"
  Expenses:Programs:Restricted:GrantFoundationA    1200.00 USD
  Assets:BankAccounts:Checking:Restricted:GrantFoundationA

The double-entry bookkeeping enforces that money from GrantFoundationA can ONLY be spent from the corresponding restricted expense account. If you try to spend restricted money on unrestricted expenses, the transaction won’t balance—Beancount will reject it.

My Questions for the Community

I’m exploring whether this approach actually works in production, especially for nonprofits managing 5-20 active grants simultaneously. Here’s what I’m trying to figure out:

1. Account Structure at Scale: For nonprofits with many grants, should each grant have its own bank account (true separation) or can we rely on the account hierarchy alone? What happens when a grant allows cost-sharing across programs?

2. Technical Enforcement: Can we write validation scripts that automatically flag transactions attempting to move restricted funds to unrestricted accounts? Something like a plugin that checks for cross-restriction transfers and raises errors?

3. Board Reporting: Non-technical board members and auditors are used to QuickBooks reports showing fund balances. How do you communicate Beancount’s structure to them? Do you generate “traditional-looking” fund balance reports from BQL queries?

4. Audit Readiness: When an auditor asks “prove you didn’t commingle Grant B funds with operational funds,” what does that proof look like in Beancount? Can we generate a complete transaction history for a specific grant with balance assertions confirming the math?

The Stakes

The nonprofit sector handles billions in restricted grant funding annually. Compliance is non-negotiable—non-compliance can lead to lawsuits from donors, IRS fines, loss of tax-exempt status, and severe reputational damage.

If Beancount can provide a better technical solution to prevent commingling—one that’s structurally sound rather than relying on bookkeeper discipline—that’s a huge value proposition for nonprofits.

Has anyone built this in production? Are there templates, validation scripts, or reporting workflows you’re willing to share? I’m particularly interested in hearing from anyone who’s successfully taken a nonprofit through an audit using Beancount for grant accounting.

Sources: Managing Restricted Funds - Propel Nonprofits, Grant Compliance and Fund Management, Restricted Funds Best Practices

2

I’ve been managing a small nonprofit’s books (about $250K annual budget with 3 active grants) using Beancount for the past 18 months, and I can share what’s actually worked for us in practice.

Our Account Structure

We use the hierarchy approach Alice described, but with one key addition—metadata tags to track additional grant details:

2026-02-10 * "Youth program supplies" #grant-abc #program-education
  Expenses:Programs:Restricted:GrantABC    850.00 USD
    grant_id: "ABC-2025-001"
    grant_period: "2025-2027"
    program: "Youth Education"
  Assets:BankAccounts:Checking:Restricted:GrantABC

This gives us both structural separation (the account hierarchy prevents commingling) AND flexible filtering (we can query by grant_id, program, or period for different reports).

Technical Enforcement Through Balance Assertions

Here’s the critical piece: we use balance assertions at the end of each month to verify restricted fund balances match exactly what they should be:

2026-02-28 balance Assets:BankAccounts:Checking:Restricted:GrantABC    14250.00 USD
2026-02-28 balance Expenses:Programs:Restricted:GrantABC               35750.00 USD

If someone accidentally tries to commingle funds, the assertions fail immediately. It’s not a validation script—it’s built into the ledger itself. The assertions also serve as audit trail markers showing we verified balances monthly.

The Git History Advantage

One thing Alice didn’t mention: the Git commit history is phenomenal for audit readiness. When the auditor asked “show me every transaction for Grant ABC,” I ran:

git log --all --full-history --grep="grant-abc" -- nonprofit.beancount

This showed not just the transactions, but who entered them, when, and what the commit message said. It’s an immutable audit trail that QuickBooks can’t provide.

Reality Check

I’ll be honest though—getting the nonprofit’s board treasurer comfortable with this took time. He kept asking “where’s the fund balance report like QuickBooks shows?” I ended up writing a simple Python script that generates a traditional fund balance report from BQL queries. It made everyone happy.

Happy to share our basic account template if others are interested. The key insight is that Beancount’s structure makes commingling technically impossible rather than just “against policy.”

3

This is timely—I’m currently converting two nonprofit clients from QuickBooks to Beancount, and the restricted fund tracking is both the biggest opportunity AND the biggest challenge.

The Good: Validation Scripts Caught an Error

Last month, one of my clients had a bookkeeper accidentally try to pay unrestricted overhead costs from a restricted grant account. Our validation script caught it before it went through:

# Simple plugin that checks for cross-restriction transfers
def check_restriction_boundaries(entries):
    for entry in entries:
        if isinstance(entry, Transaction):
            restricted_accounts = [p for p in entry.postings
                                  if 'Restricted' in p.account]
            unrestricted_accounts = [p for p in entry.postings
                                    if 'Unrestricted' in p.account]

            if restricted_accounts and unrestricted_accounts:
                # Flag transactions mixing restricted and unrestricted
                yield error(entry, "Cannot mix restricted and unrestricted funds")

It’s crude but effective. The bookkeeper got an error message immediately instead of creating an audit problem six months later.

The Challenge: Board Communication

Here’s the hard part Alice is asking about—nonprofits live and die by board reports, and boards expect specific formats. Our funders want:

  1. Grant balance report showing “Amount Awarded / Amount Spent / Amount Remaining”
  2. Program expense breakdown by grant
  3. Narrative report explaining variances

I generate these monthly from BQL queries, export to CSV, and import into a Google Sheets template that matches the format funders expect. It takes about 30 minutes per month per grant. Not perfect, but it works.

Monthly Reporting Workflow

For anyone building this, here’s our actual workflow:

  1. Week 1-3: Enter transactions as they occur (daily bank downloads, weekly receipt processing)
  2. Week 4: Run reconciliation and balance assertions
  3. Month-end: Generate funder reports
    • Run BQL query: SELECT account, sum(position) WHERE account ~ 'GrantXYZ'
    • Export to CSV
    • Load into Google Sheets template
    • Add narrative
    • Send PDF to program director for review
  4. Follow-up: Program director confirms narrative, we send to funder

The Harsh Reality

Much as I love Beancount’s technical elegance, I have to be honest: most small nonprofits ($200K-$500K budgets) aren’t ready for this. They need:

  • Bookkeeper who understands both accounting AND plain text / Git workflows
  • Executive director who trusts “weird” accounting setup
  • Board members willing to read non-standard reports
  • Technical capacity to troubleshoot when things break

That’s a high bar. I’ve found the sweet spot is nonprofits with $500K+ budgets where they’re already paying for QuickBooks Premier ($600/year) or considering Aplos ($1200/year). At that scale, the investment in Beancount setup pays off.

Would love to hear from others on what the minimum viable nonprofit size/sophistication is for this approach.

4

Coming at this from a different angle—I’m primarily a FIRE tracker, not a professional bookkeeper, but I’ve hit the exact same problem with a different use case: tracking separate savings goals.

The Personal Finance Parallel

In personal finance, “commingling” happens when you mentally allocate savings to specific goals (Emergency Fund: $10K, House Down Payment: $30K, Vacation Fund: $5K) but they all sit in one checking account. It’s easy to accidentally “borrow” from the house fund to cover vacation spending.

The Beancount solution is identical—create virtual sub-accounts:

Assets:Savings:Emergency
Assets:Savings:HouseDownPayment
Assets:Savings:Vacation

Now transfers are explicit: Assets:Savings:Vacation → Expenses:Travel. If you overspend vacation budget, you have to explicitly record a transfer from HouseDownPayment, which makes the “borrowing” visible.

The Technical Implementation

For nonprofits, I’d suggest going further with a Python plugin that not only flags cross-restriction transfers (like Bob showed) but also generates automated reports.

Here’s what I built for personal savings tracking (could be adapted for grants):

def generate_goal_balance_report(entries):
    """Generate a savings goal balance report"""
    balances = {}
    for entry in entries:
        for posting in entry.postings:
            if posting.account.startswith('Assets:Savings:'):
                goal = posting.account.split(':')[-1]
                balances[goal] = balances.get(goal, 0) + posting.units.number

    return balances

This runs automatically and outputs a simple report: “Emergency: $10,243 | House: $31,450 | Vacation: $4,890”. For nonprofits, it’d be “GrantA: $14,250 | GrantB: $28,100 | Unrestricted: $12,450”.

Comparison to Commercial Tools

I looked at commercial nonprofit software (Aplos, QuickBooks Nonprofit) and they handle this through “fund codes” or “classes.” But those are just tags—they don’t prevent commingling structurally. You can assign the wrong fund code to a transaction and the software happily accepts it.

Beancount’s account hierarchy means the structure enforces the separation. That’s a fundamentally stronger guarantee.

ROI Question

The big question is whether the setup effort is worth it. For my personal finances with 5 savings goals, it took me about 4 hours to set up the account structure and write the reporting script. Now it runs automatically.

For a nonprofit with 10-15 grants, I’d estimate:

  • Initial setup: 20-40 hours (account structure, validation plugins, report templates)
  • Ongoing maintenance: 2-4 hours/month (mostly report generation)
  • One-time learning curve: 40-80 hours for bookkeeper to get comfortable

At bookkeeper rates of $40-60/hour, that’s $3,200-$7,200 in year one, then $960-$2,880/year ongoing.

Compare to Aplos at $1,200/year or QuickBooks Nonprofit Premier at $600/year—Beancount is more expensive upfront but comparable or cheaper by year 3-5, plus you own the system and it’s infinitely customizable.

The real question is: do you have someone technical enough to maintain it? That’s the bottleneck.

5

This discussion is exactly what I was hoping for—thank you Mike, Bob, and Fred for sharing real implementations!

Key Takeaways

From what I’m hearing, the technical solution works well:

  1. Account hierarchy structurally prevents commingling (can’t spend Grant A money on Unrestricted expenses without explicitly recording a transfer)
  2. Balance assertions provide monthly checkpoints that catch errors immediately
  3. Git history creates immutable audit trail better than commercial software
  4. Validation plugins add automated guardrails on top of structural separation

The Real Barrier: Organizational Capacity

But Bob’s point about organizational readiness is crucial. The technical sophistication required is higher than QuickBooks:

  • Understanding account hierarchy design
  • Writing/maintaining validation scripts
  • Generating reports from BQL queries
  • Troubleshooting when assertions fail
  • Explaining the system to boards and auditors

This probably limits Beancount nonprofit adoption to organizations with:

  • $500K+ annual budgets (ROI justifies investment)
  • Tech-savvy finance staff or access to technical bookkeeper
  • Leadership willing to trust non-standard approach
  • Audit firm comfortable with plain text accounting

Proposal: Nonprofit Beancount Starter Kit

Given the interest here, what if we collaborated on a “Nonprofit Grant Accounting Starter Kit”? This would include:

  1. Reference account structure for common grant scenarios
  2. Validation plugin library (cross-restriction checks, budget alerts)
  3. Report templates that generate funder-friendly output
  4. Audit readiness guide (what auditors ask for, how to provide it from Beancount)
  5. Board communication examples (how to explain this to non-technical stakeholders)

This could significantly reduce the 40-80 hour learning curve Fred estimated.

Compliance Resources

For anyone exploring this, I strongly recommend reviewing:

  • ASC 958 (FASB standard for nonprofit accounting)
  • UPMIFA (Uniform Prudent Management of Institutional Funds Act)
  • Your state’s specific nonprofit financial management requirements

The technical elegance of Beancount doesn’t matter if we’re not compliant with these standards. But I believe we can be—and actually more compliant than QuickBooks due to structural enforcement rather than relying on bookkeeper discipline.

Would others be interested in collaborating on the starter kit? I can contribute the account structure templates and compliance guidance from a CPA perspective.