7 posts tagged with "double-entry accounting"

Journal entries are the backbone of double-entry accounting, and in Beancount, every * transaction you write is a journal entry. This guide explains the essentials—debits and credits, adjusting entries, and reversing entries—and shows how they map cleanly to Beancount's plain-text syntax. You'll learn how to keep precise books with minimal ceremony.

A Quick Refresher: What Is a Journal Entry?​

A journal entry is the formal, dated record of a financial transaction. It's expressed in terms of debits and credits that keep the fundamental accounting equation in balance:

$Assets = Liabilities + Equity$

In a double-entry system, every transaction affects at least two accounts, and the total debits must equal the total credits. This simple rule is what makes downstream financial reports like the Profit & Loss statement and Balance Sheet trustworthy and accurate.

Debits and Credits in One Minute​

The concepts of debits and credits can be confusing at first, but they boil down to a few simple rules. Think of it this way: "where did the value come from?" (credit) and "where did the value go?" (debit).

Here's a cheat sheet for how they increase the five core account types:

How a Journal Entry Looks in Beancount​

Beancount uses simple, human-readable text directives to record transactions. Each transaction must balance to zero for every commodity (e.g., USD, EUR, AAPL stock). Beancount will throw an error if it doesn't.

Here is a basic transaction for buying coffee:

2025-09-10 * "Coffee Bar" "Team coffee"
  Expenses:Food:Coffee          18.00 USD
  Assets:Bank:Checking         -18.00 USD

Notice how the two postings (lines with accounts) sum to zero: $18.00 + (-$18.00) = 0.

You can add powerful context directly in the narration using tags (like #clientX) for filtering and links (like ^INV-2025-001) to connect related entries.

For example, here's how you can link an invoice to its payment:

; First, record the invoice you sent to the client
2025-09-15 * "Acme Corp" "Invoice 2025-001 #clientX ^INV-2025-001"
  Assets:AccountsReceivable   1000.00 USD
  Income:Consulting         -1000.00 USD

; Later, record the payment and link it back to the original invoice
2025-09-28 * "Acme Corp" "Payment on ^INV-2025-001"
  Assets:Bank:Checking       1000.00 USD
  Assets:AccountsReceivable -1000.00 USD

The #clientX tag lets you easily filter all transactions for this client, and the ^INV-2025-001 link creates a connection between the two entries that you can follow in reports.

Common Journal Entries (Ready to Paste)​

Here are several common business transactions formatted for Beancount.

Owner Invests Cash​

An owner contributes personal funds to start the business.

2025-01-01 * "Owner" "Initial capital contribution"
  Assets:Bank:Checking        10000.00 USD
  Equity:Owner-Capital      -10000.00 USD

Cash Sale with Sales Tax​

A customer pays in cash for a product, including an 8% sales tax you must later remit to the government.

2025-01-05 * "Walk-in Customer" "Cash sale with 8% tax"
  Assets:Cash                   108.00 USD
  Income:Sales                -100.00 USD
  Liabilities:Tax:Sales         -8.00 USD

Sale on Credit (Invoice) and Collection​

You provide a service and invoice the client, then receive payment later.

2025-01-10 * "Acme Corp" "Consulting invoice ^INV-2025-002"
  Assets:AccountsReceivable   2500.00 USD
  Income:Consulting         -2500.00 USD

2025-01-30 * "Acme Corp" "Payment on ^INV-2025-002"
  Assets:Bank:Checking       2500.00 USD
  Assets:AccountsReceivable -2500.00 USD

Expense on Credit Card​

You purchase office supplies using a company credit card.

2025-01-12 * "OfficeMax" "Supplies on credit card"
  Expenses:Office:Supplies       75.00 USD
  Liabilities:CreditCard        -75.00 USD

Payroll (Simple Model)​

You run payroll, recording the gross wage expense, employee tax withholdings, and the net payment from your bank.

2025-01-31 * "Payroll" "January wages and withholdings"
  Expenses:Payroll:Wages      2000.00 USD
  Liabilities:Taxes:Withheld   -400.00 USD
  Assets:Bank:Checking       -1600.00 USD

Monthly Depreciation​

You record the monthly depreciation expense for an asset, like a laptop.

2025-01-31 * "Depreciation" "Laptop, straight-line"
  Expenses:Depreciation          100.00 USD
  Assets:Equipment:AccumDepr    -100.00 USD

Prepaid Expense & Monthly Amortization​

You pay for a full year of insurance upfront, then recognize one month's worth of the expense.

; 1. Pay for the annual policy
2025-01-01 * "InsureCo" "Annual insurance premium"
  Assets:Prepaid:Insurance     1200.00 USD
  Assets:Bank:Checking       -1200.00 USD

; 2. Recognize one month of expense at the end of January
2025-01-31 * "InsureCo" "Amortize 1/12 of insurance"
  Expenses:Insurance             100.00 USD
  Assets:Prepaid:Insurance      -100.00 USD

Unearned Revenue & Monthly Recognition​

A customer prepays for a 3-month subscription. You record the cash and then recognize one month of income.

; 1. Customer prepays for service
2025-02-01 * "Subscriber" "3-month plan prepaid"
  Assets:Bank:Checking           300.00 USD
  Liabilities:Unearned:Subs     -300.00 USD

; 2. Recognize one month of income after delivering the service
2025-02-28 * "Recognition" "Recognize month 1 of 3"
  Liabilities:Unearned:Subs      100.00 USD
  Income:Subscriptions          -100.00 USD

Bad-Debt Allowance and Write-Off​

You set aside an allowance for potentially uncollectible invoices and later write off a specific bad invoice.

; 1. Create a provision based on 2% of Accounts Receivable
2025-03-31 * "Provision" "2% of A/R for doubtful accounts"
  Expenses:BadDebt               200.00 USD
  Assets:AllowanceForDoubtful   -200.00 USD

; 2. Write off a specific invoice that you know will not be paid
2025-04-15 * "Write-off" "Customer XYZ invoice"
  Assets:AllowanceForDoubtful    150.00 USD
  Assets:AccountsReceivable     -150.00 USD

Periodic Inventory & COGS Adjustment​

At the end of a period, you calculate the Cost of Goods Sold (COGS) by adjusting your inventory account.

2025-03-31 * "COGS adjustment" "Periodic inventory method"
  Expenses:COGS                4500.00 USD
  Assets:Inventory           -4500.00 USD

Adjusting Entries vs. Reversing Entries​

Adjusting entries are recorded at the end of an accounting period (like a month or quarter) to properly align revenues and expenses to the period in which they were actually earned or incurred. This includes accruals, deferrals, and estimates like depreciation.

Reversing entries are optional entries made on the first day of a new period that exactly reverse a specific adjusting entry from the prior period. Their purpose is to simplify bookkeeping. By reversing an accrual, you can book the subsequent cash transaction in a standard way without having to remember to split it against the liability account.

Example: Accruing and Reversing Utilities​

Let's say you need to record your January utility expense, but the bill won't arrive until February.

; 1. Accrue the estimated expense at the end of January
2025-01-31 * "Accrual" "Estimate January utilities expense"
  Expenses:Utilities              500.00 USD
  Liabilities:Accrued:Utilities  -500.00 USD

; 2. (Optional) Reverse the accrual on the first day of the next period
2025-02-01 * "Reversal" "Undo January utilities accrual"
  Liabilities:Accrued:Utilities   500.00 USD
  Expenses:Utilities             -500.00 USD

; 3. Record the actual bill payment when it arrives in February
; The actual bill is for $520. Because of the reversal, you can
; book the full amount to the expense account without issue.
; The net expense for Feb will be $520 - $500 = $20.
2025-02-10 * "City Utilities" "Payment for January bill"
  Expenses:Utilities             520.00 USD
  Assets:Bank:Checking          -520.00 USD

Note: The example in the outline shows splitting the final payment. The reversing entry method is an alternative that simplifies the final payment entry.

A Checklist for Every Beancount Journal Entry​

Follow these steps to ensure your entries are clean and correct:

1. Start with the date (YYYY-MM-DD) and a transaction flag (*).
2. Add a payee and a descriptive narration. Use #tags and ^links for searchability.
3. Include at least two posting lines that balance to zero for each commodity.
4. Use proper account names under the five types: Assets, Liabilities, Equity, Income, Expenses.
5. Optionally, add metadata like document: "invoices/INV-2025-001.pdf" for traceability.

Common Pitfalls (and How Beancount Helps)​

• Imbalanced Postings: If your debits and credits don't sum to zero, Beancount will refuse the entry. This is a core feature that prevents errors. You can even leave one posting amount blank, and Beancount will automatically calculate it for you.
• Wrong Sign on an Account: It's easy to forget that Income, Equity, and Liabilities are increased with credits (which are typically negative numbers in Beancount). If you get it wrong, your reports will look strange, but the balancing rule still provides a safety net.
• Missing Links Between Entries: Forgetting to link an invoice to its payment makes it harder to track what's outstanding. Using ^links consistently solves this by creating an auditable trail.

Where to Go Next​

• Beancount Language & Balancing Rules: Dive deeper into the official documentation.
• Syntax Cheat Sheet: A handy reference for all Beancount directives.
• Debits/Credits Primer: A great starting point if you're new to accounting rules.
• Adjusting/Reversing Entries: More detailed articles on the accounting theory.

Appendix: Accounting Talk → Beancount Map​

This quick translation guide can help you map accounting instructions to Beancount syntax.

With these patterns and examples, you can cleanly model nearly any business event in Beancount, ensuring your financial reports line up without any surprises.

Taxes can feel like a special, complicated beast in the world of personal finance. But what if they weren't? What if you could treat them just like any other flow of money in your ledger? Good news: you can. By treating taxes as simple movements of value, your Beancount ledger will stay clean, easy to query, and—most importantly—understandable.

Below is a practical, no-nonsense pattern you can drop into a personal or small-business Beancount file. It’s a simple system for handling paychecks, tax payments, and even those pesky refunds that cross over into the new year. We'll cover the essential accounts you need, walk through real-world examples, and show you the exact queries to run to get the answers you need.

The Core Principles​

Before we dive into the code, let's agree on a few simple rules. These principles keep things logical and prevent future headaches.

• Separate "what it is" from "when the cash moves." 🗓️ This is the most important concept. A tax expense belongs to the year you earned the income (e.g., 2024), even if you settle the bill with the IRS in April 2025. If you don't separate the timing of the expense from the timing of the cash payment, your year-over-year reports will get messy and misleading.

• Keep your account hierarchy boring and simple. 📁 Name your accounts clearly based on the type of tax (e.g., IncomeTax, SocialSecurity). This makes your queries incredibly simple. Don't clutter account names with vendor names or form numbers like "W-2" or "1099"; use metadata and tags for those details instead.

• Embrace accrual for year-end adjustments. ⚖️ Even for a personal ledger, using a simple accrual entry at year-end is the cleanest way to make your reports accurate. It means recognizing an expense or refund in the correct year, even if the money doesn't move until the next. It’s one small extra step that saves you from mental gymnastics later.

• Write for your future self. 🧠 Your goal is clarity. Only add extra details, like the tax year, to an account name if it genuinely makes your queries easier. Avoid creating a new set of accounts every single year (Expenses:Taxes:2024:Federal, Expenses:Taxes:2025:Federal, etc.) unless you have a compelling reason. A flat structure is often easier to manage.

A Minimal Account Skeleton​

Here’s a basic set of accounts to get you started. This structure is US-centric, but you can easily adapt the names for your own country's tax system. Just drop these open directives into your Beancount file.

; --- US Federal Income & Payroll Taxes ---
; For money withheld from your paycheck
2024-01-01 open Expenses:Taxes:Federal:IncomeTax:Withheld       USD
; For estimated payments or tax-day bills you pay directly
2024-01-01 open Expenses:Taxes:Federal:IncomeTax:Payments       USD
; For tax refunds you receive
2024-01-01 open Expenses:Taxes:Federal:IncomeTax:Refunds        USD

; Your FICA contributions
2024-01-01 open Expenses:Taxes:Federal:SocialSecurity           USD
2024-01-01 open Expenses:Taxes:Federal:Medicare                 USD

; --- Other Common Taxes ---
; For sales/use taxes you pay on purchases
2024-01-01 open Expenses:Taxes:Sales                            USD

; --- Accounts for Year-End Adjustments (Optional but Recommended!) ---
; A temporary holding account for taxes you owe but haven't paid yet
2024-01-01 open Liabilities:AccruedTaxes:Federal:Income         USD
; A temporary holding account for a refund you're owed but haven't received
2024-01-01 open Assets:Tax:Receivable                           USD

This setup separates withheld taxes from direct payments and refunds, making it easy to see exactly where your money went. The Liabilities and Assets accounts are our secret weapon for keeping year-end reporting accurate.

Example 1: The Paycheck​

Let's book a typical paycheck where taxes are withheld automatically. The key is to record your gross pay first, then show how it was split between taxes and the cash that actually landed in your bank account.

2025-07-15 * "Employer Inc." "Salary for first half of July"
  Income:Work:Salary                                  -6,000.00 USD
  Expenses:Taxes:Federal:IncomeTax:Withheld             1,200.00 USD
  Expenses:Taxes:Federal:SocialSecurity                   372.00 USD
  Expenses:Taxes:Federal:Medicare                          87.00 USD
  Assets:Cash:Checking                                  4,341.00 USD

This single transaction tells the whole story:

• You earned $6,000 in gross income.
• $1,200 of it was sent to the IRS for federal income tax.
• $372 went to Social Security and$87 to Medicare.
• The remaining $4,341 is what you took home.

Pro-tip: You can attach metadata from your pay stub (like pay_period_end: "2025-07-15") to the transaction for an easy audit trail.

Example 2: Filing Your Return (The Year-Crossing Problem)​

Here's the scenario that trips people up: It's April 2025, and you're filing your 2024 taxes. You learn that after all your withholding, you still owe an extra $3,000.

How do you record this? You want the expense to count toward 2024, but the cash payment happens in 2025. Here are two excellent ways to handle it.

Option A: The Manual Two-Step Accrual​

This method is pure Beancount, no plugins required. It's a clear, two-step process.

Step 1: Recognize the expense at the end of the tax year. On the last day of 2024, you create a "true-up" entry. No cash is moving yet; you're just acknowledging the expense and parking it in a temporary liability account.

2024-12-31 * "Federal income tax true-up for 2024"
  Expenses:Taxes:Federal:IncomeTax:Payments             3,000.00 USD
  Liabilities:AccruedTaxes:Federal:Income             -3,000.00 USD

Now, your 2024 income statement correctly shows this $3,000 expense.

Step 2: Record the cash payment when it happens. In April 2025, when you actually send the money to the IRS, you clear out the liability.

2025-04-15 * "IRS" "Payment for 2024 tax return"
  Liabilities:AccruedTaxes:Federal:Income              3,000.00 USD
  Assets:Cash:Checking                                -3,000.00 USD

Your 2024 reports are correct, and your 2025 cash flow is correct. Perfect! This same pattern works in reverse for a refund—just use Assets:Tax:Receivable instead of the liability account.

Option B: Automate It with a Plugin​

If you prefer to keep the payment in a single transaction, a fantastic community plugin called beancount_reds_plugins.effective_date can help. It lets you assign a different "effective date" to a single line item.

First, enable the plugin in your main Beancount file: plugin "beancount_reds_plugins.effective_date"

Now, you can write a single transaction. The plugin will automatically split it behind the scenes to make your reports accurate.

; One entry; the plugin handles the rest
2025-04-15 * "IRS" "Payment for 2024 tax return"
  Assets:Cash:Checking                                 -3,000.00 USD
  Expenses:Taxes:Federal:IncomeTax:Payments             3,000.00 USD
    effective_date: 2024-12-31

Here, the cash portion is recorded on April 15, 2025, but the expense portion is retroactively applied to December 31, 2024. It achieves the same result as Option A with a different workflow.

What About Sales Tax?​

For most personal ledgers, sales tax is simple. If you're not claiming it back, just split it out as its own expense during a purchase.

2025-07-19 * "Local Grocery Store"
  Expenses:Groceries                                      12.32 USD
  Expenses:Taxes:Sales                                     1.28 USD
  Assets:Cash:Checking                                   -13.60 USD

This lets you easily track how much you're spending on sales tax over the year. If you run a business that deals with VAT, you'd use a more formal system with payable and receivable accounts, but the principle is the same.

Queries You'll Actually Run​

The whole point of this structure is to make getting answers easy. Here are some BQL queries to see your tax picture.

1. What was my total federal income tax for 2024?

SELECT cost(sum(position))
WHERE account ~ "Expenses:Taxes:Federal:IncomeTax"
  AND date >= 2024-01-01 AND date < 2025-01-01;

2. How did that total break down between withholding, payments, and refunds?

SELECT account, cost(sum(position))
WHERE account ~ "Expenses:Taxes:Federal:IncomeTax"
  AND date >= 2024-01-01 AND date < 2025-01-01
GROUP BY account
ORDER BY account;

3. Do I have any outstanding tax debts or receivables? (Useful for checking your work!)

SELECT account, units(sum(position))
WHERE account ~ "Liabilities:AccruedTaxes" OR account ~ "Assets:Tax"
GROUP BY account
ORDER BY account;

If this query returns non-zero balances, it means you have accruals you haven't settled yet.

Quick FAQ​

• Do I really need per-year accounts like Expenses:Taxes:2024? Probably not. The accrual method (or the plugin) keeps a flat account structure clean and readable. Only create per-year accounts if you find it makes your specific queries easier to write.

• Can Beancount calculate my taxes for me? Not directly, but it can prepare the data. Some advanced users write scripts to pipe BQL query results into tax calculation software, which is great for estimating your liability during the year.

• Is this tax advice? No. This is a bookkeeping pattern for organizing your data. The accounting is sound, but you should always consult a tax professional for advice specific to your situation.

Your Drop-In Checklist​

Ready to get started?

1. ✅ Add the account skeleton to your Beancount file (and adapt names for your country).
2. ✅ Book paychecks by starting with gross income and splitting out the tax postings.
3. ✅ At year-end, accrue any true-ups for payments or refunds using a liability/asset account (or use the effective_date plugin).
4. ✅ Track refunds as receivables and clear them when the cash arrives.
5. ✅ Run the BQL queries above to verify your totals before you file.

Keep it boring, keep it consistent, and your tax season will finally feel like just another part of your financial story—not a mystery to be solved.

Financial statements don't appear by magic. They are the final product of a structured, repeatable process known as the accounting cycle. While the principles are universal, the tools you use can dramatically change the experience. This guide walks you through the accounting cycle with a focus on Beancount, the powerful plain-text accounting tool.

We'll see how Beancount's text-first approach eliminates tedious steps, what you should automate, and which reports give you the clearest picture of your financial health. 🧑‍💻

TL;DR: The Beancount Workflow​

• Capture & Journal: Record every transaction as a clean, double-entry posting in your .beancount text file.
• Validate & Reconcile: Use balance assertions to confirm your ledger matches bank statements and run bean-check to catch errors.
• Review: Generate an unadjusted trial balance for a quick sanity check.
• Adjust: Post entries for accruals, deferrals, depreciation, and other period-end items.
• Re-review: Check the adjusted trial balance to ensure everything is correct.
• Publish & Close: Generate your Income Statement, Balance Sheet, and Cash Flow statement. Closing the books is optional in Beancount, as reports are date-aware.

This flow can be visualized like this:

Step 1: Capture and Record Transactions​

This is the foundational step. Every financial event—a sale, a purchase, a bank fee—must be recorded. In Beancount, you do this by creating transactions in a simple text file, typically named main.beancount or organized into multiple files by year.

Each transaction must follow the rules of double-entry bookkeeping, meaning the sum of all postings must be zero. Beancount enforces this for you.

2025-08-10 * "Walmart" "Purchase of office supplies"
  Expenses:Office:Supplies      45.67 USD
  Assets:Bank:Checking         -45.67 USD

• Pro-Tip: Use tags like #project-phoenix or #client-acme to add dimensions to your data. This makes querying and reporting incredibly flexible later on.

Reconciliation Hygiene ✅​

The most powerful feature for ensuring accuracy is the balance assertion. At the end of a statement period (e.g., end of the month), you declare what the balance of an account should be.

2025-08-31 balance Assets:Bank:Checking  12345.67 USD

If the sum of all transactions affecting Assets:Bank:Checking up to that date doesn't equal 12345.67 USD, Beancount will raise an error. This simple directive turns your ledger into a self-auditing document.

For those backfilling historical data, the pad directive can automatically create a balancing transaction to make your opening balances match your first assertion.

Step 2: "Post to the Ledger" (A Freebie!)​

In traditional accounting systems, you first write entries in a "journal," and then a separate "posting" step copies those values to the "general ledger."

With Beancount, your .beancount file is both the journal and the ledger. When you write and save a transaction, you've already posted it. There is no separate step. This directness is a core advantage of plain-text accounting—what you see is what you get.

Step 3: Prepare an Unadjusted Trial Balance​

Before you start making adjustments, you need a quick "does this all add up?" check. A trial balance is a simple report that lists every account and its total balance. The grand total of all debit balances must equal the grand total of all credit balances.

You can generate this with a simple query:

bean-query main.beancount \
  "SELECT account, sum(position) GROUP BY 1 ORDER BY 1"

Or, for a more visual approach, open your ledger in Fava (the web interface for Beancount) and navigate to the "Trial Balance" report. Look for anything unusual—an asset account with a credit balance, or an expense account with a strange value.

Step 4: Book Adjusting Entries​

Adjusting entries are crucial for accurate reporting under the accrual basis of accounting. They ensure that revenues are recognized when earned and expenses are recognized when incurred, regardless of when cash changes hands.

Common adjustments include:

• Accruals: Recording revenue you've earned but haven't invoiced yet, or an expense you've incurred but haven't paid.
• Deferrals: Handling prepayments. If a customer pays you for a year of service upfront, you book it as a liability (Liabilities:UnearnedRevenue) and recognize 1/12th of it as income each month.
• Non-Cash Items: Recording things like depreciation of assets.
• Corrections: Fixing errors or accounting for missed items from bank feeds, like a small interest payment.

Example: Accruing Revenue​

You finished a project on August 31st but won't send the invoice until September. To recognize the income in the correct period (August), you make an adjusting entry:

2025-08-31 * "Accrue revenue for client project #1042"
  Assets:AccountsReceivable      3000.00 USD
  Income:Consulting             -3000.00 USD

Example: Recording Depreciation​

Your company has a depreciation schedule for its assets. At the end of the period, you book the expense:

2025-12-31 * "Annual depreciation on computer equipment"
  Expenses:Depreciation                  4800.00 USD
  Assets:Fixed:AccumulatedDepreciation  -4800.00 USD

Step 5: Run an Adjusted Trial Balance & Validate​

Once your adjusting entries are in, run the trial balance report again. This is your Adjusted Trial Balance. It provides the final set of numbers that will be used to create the financial statements.

This is also the perfect time to run Beancount's built-in sanity check:

bean-check main.beancount

This command verifies all syntax, balancing rules, and assertions. If it runs without any output, your books are mechanically sound.

Step 6: Publish Financial Statements 📊​

This is the payoff. Using the numbers from your adjusted trial balance, you can now generate the key financial reports. Fava is the easiest way to do this, as it provides interactive, drill-down reports out of the box.

• Income Statement (Profit & Loss): Shows your revenues and expenses over a period, resulting in your net income or loss.
• Balance Sheet: A snapshot of what you own (Assets) and what you owe (Liabilities), as well as your net worth (Equity), on a specific date.
• Cash Flow Statement: Reconciles your starting cash with your ending cash by showing where money came from and where it went.

For custom reports, you can use Beancount Query Language (BQL). Here’s a query for a monthly income statement:

-- P&L for August 2025
SELECT account, sum(position)
WHERE account ~ '^(Income|Expenses)'
  AND date >= 2025-08-01 AND date <= 2025-08-31
GROUP BY account ORDER BY account;

Step 7: Closing the Books (Optional)​

In traditional accounting, the "closing" process involves creating journal entries to zero out all temporary accounts (Income and Expenses) and transfer the net income into an equity account called Retained Earnings. This formally resets the temporary accounts for the next year.

In Beancount, this step is usually unnecessary. Fava's reports are date-aware; if you ask for a 2025 P&L, it will only use 2025 data. The balances don't "spill over." Most users simply leave the balances as they are.

However, if you need to perform a formal close for compliance or shareholder reporting, you can do so with a simple year-end transaction that moves the total income and expense balances into Equity:Retained-Earnings.

A Practical Monthly Close Checklist​

Here’s a repeatable checklist to close your books each month using Beancount.

• Capture: Import all bank and credit card transactions. Manually enter any cash expenses or out-of-band items.
• Reconcile: Add balance assertions for all bank accounts, credit cards, and loan accounts, matching them to your statements.
• Review: Scan the unadjusted trial balance in Fava. Investigate any strange or unexpected balances. Check for stale unpaid invoices (Assets:AccountsReceivable) or bills (Liabilities:AccountsPayable).
• Adjust: Book entries for accrued revenue/expenses, deferred revenue, and any necessary corrections.
• Validate: Run bean-check. Review the final adjusted trial balance.
• Publish: Generate the P&L and Balance Sheet. Send them to stakeholders or save them for your records.
• Wrap-up: Optionally, perform a closing entry if your business requires it. Archive a copy of your .beancount files for the period.

Why Beancount Shines for the Accounting Cycle​

• Transparency and Auditability: Your ledger is a text file. You can use git to version control your financial history, review changes with diff, and collaborate with your accountant in a clear, unambiguous format.
• Total Control: You define your chart of accounts. You aren't locked into a software vendor's structure. Your data is yours, forever, in an open format.
• Unmatched Power: The combination of SQL-like queries (BQL) and a rich web interface (Fava) gives you unparalleled power to slice, dice, and understand your financial data.

Copy-Paste Snippets to Get Started​

Simple Chart of Accounts:

option "title" "My Personal Ledger"
option "operating_currency" "USD"

;; --- Accounts ---
1970-01-01 open Assets:Bank:Checking
1970-01-01 open Assets:AccountsReceivable
1970-01-01 open Liabilities:CreditCard
1970-01-01 open Liabilities:UnearnedRevenue
1970-01-01 open Equity:Owner:Capital
1970-01-01 open Equity:Retained-Earnings
1970-01-01 open Income:Consulting
1970-01-01 open Expenses:Office:Supplies
1970-01-01 open Expenses:Software
1970-01-01 open Expenses:Depreciation

Useful BQL Query:

-- Find all customers with an outstanding balance
SELECT payee, sum(position)
WHERE account = 'Assets:AccountsReceivable'
GROUP BY payee
HAVING sum(position) > 0
ORDER BY sum(position) DESC;

By mapping the timeless accounting cycle to Beancount's modern, text-based tools, you gain a system that is robust, transparent, and built to last. Happy bookkeeping!

For decades, the world of business accounting has been dominated by a familiar cast of closed, GUI-based systems like QuickBooks, Xero, and FreshBooks. They have set the standard, offering ease-of-use and visual workflows that cater to non-technical users. But for developers, power users, and anyone who values absolute transparency and control, a radically different approach has emerged: Beancount.io.

This article provides a direct comparison of Beancount.io with traditional accounting software. We'll break down their core differences in philosophy, flexibility, cost, and long-term maintainability to help you decide which system truly fits your needs.

1. Philosophy and Workflow​

The most fundamental difference between these two approaches lies in their core philosophy.

Beancount.io Beancount.io is built on the philosophy of plain-text accounting. At its heart, every single financial transaction is an entry in a simple text file. This "accounting as code" model prioritizes human-readable, version-controllable records. Your financial data lives in a timeless, open format that you own completely—it can never be locked away by a vendor. This workflow is designed for users who are comfortable with code editors, version control systems like Git, and command-line tools.

Traditional Software Traditional accounting platforms are GUI-based and form-driven. You enter data using wizards, dropdown menus, and visual forms. This approach prioritizes immediacy and accessibility, making it easy for non-technical users to get started without a steep learning curve. However, your data is stored in a proprietary format or a cloud database, often requiring complex export and import procedures if you ever decide to migrate to another service.

Verdict: If you prioritize full control, data ownership, transparency, and automation, Beancount.io is the clear winner. If you need a "click and go" interface with a minimal learning curve, traditional software will feel more natural.

2. Flexibility and Customization​

How well can the software adapt to your specific needs?

Beancount.io Being 100% scriptable is Beancount.io’s superpower. It integrates seamlessly with Python, allowing you to connect to any API, automate data fetching from bank feeds, programmatically tag transactions based on complex rules, and generate custom reports tailored to your exact specifications. Your ability to extend and customize is practically infinite, free from any vendor-imposed limitations.

Traditional Software These platforms offer a curated selection of integrations with popular tools like PayPal, Stripe, and various payroll services. While convenient, you are operating within the vendor's walled garden. Customization is limited to what the platform allows, and advanced reporting or automation often requires upgrading to a higher-tier plan or purchasing third-party add-ons. You can work with their APIs, but you'll always be bound by their ecosystem's rules and rate limits.

Verdict: Beancount.io provides unmatched flexibility for developers and technical users. Traditional tools are better suited for standard, plug-and-play workflows with popular business applications.

3. Collaboration and Transparency​

How you work with others and audit your records differs significantly.

Beancount.io Collaboration on Beancount.io is managed through Git. This makes every change to your financial ledger completely transparent and auditable. You can see who changed what, when, and why—just like a code review workflow. This is ideal for distributed teams that already embrace tools like GitHub or GitLab. Furthermore, there are no hidden calculations; every number in a report can be traced back to the exact line-item entry in your ledger file, ensuring complete auditability.

Traditional Software Collaboration is handled through built-in user roles and permissions. You can invite your accountant, bookkeeper, or business partners to access the books directly through the web interface. This is highly effective for businesses that follow a traditional model of financial oversight. The downside is that some internal operations, like tax calculations or automated balance adjustments, can be opaque "black boxes," making it difficult to independently verify the logic.

Verdict: Beancount.io is perfect for teams that value granular auditability and code-style collaboration. Traditional systems are more accountant-friendly for real-time, shared GUI access.

4. Cost and Ownership​

The financial models and the concept of data ownership are worlds apart.

Beancount.io The core Beancount software is open-source and free. You only pay for the value-added services of Beancount.io, which include hosting, intelligent automation, and premium features. There are no per-seat licensing fees, so you can scale your team without incurring extra costs. Most importantly, there is zero vendor lock-in. Your data is a collection of text files that you can move, edit, or store anywhere, anytime.

Traditional Software These services operate on a subscription model, typically billed monthly or yearly. Pricing is often tiered based on features, and you may face per-user or per-company fees that scale with your organization. This creates a dependency; if you stop paying, you risk losing access to your data and the software's functionality. This vendor lock-in is a significant long-term risk.

Verdict: Beancount.io is significantly more cost-effective in the long run, especially for technical teams that value data sovereignty. Traditional software offers predictable subscription costs but creates long-term dependency.

5. Learning Curve and Adoption​

How quickly can you get up and running?

Beancount.io The learning curve is undeniably steeper. Adopting this system requires comfort with text-based editing, understanding basic syntax, and familiarity with tools like Git. However, the initial investment pays off. Once mastered, Beancount enables incredibly fast, repeatable workflows and provides a much deeper, foundational understanding of your financial picture.

Traditional Software These platforms are designed for non-technical business owners and offer minimal onboarding friction. You can be up and running, sending invoices and categorizing expenses, within minutes. That said, learning the more advanced features, such as custom report building or setting up multi-entity accounting, still requires a significant time investment.

Verdict: Beancount.io is the right choice if you're willing to invest time in learning a powerful system. Traditional software is faster to start with for non-technical users who need immediate results.

Side-by-Side Comparison​

When to Choose Each​

The decision ultimately comes down to your team's skills, priorities, and workflow.

Choose Beancount.io if you:

• Are a developer, data analyst, or technically-inclined power user.
• Value absolute transparency, control, and long-term data portability above all else.
• Want to fully automate your accounting and integrate it deeply into your custom workflows.
• Are comfortable treating your financial records with the same rigor as source code.

Choose Traditional Accounting Software if you:

• Want a quick-start, visual interface without any technical setup.
• Need to provide immediate, accountant-friendly access with minimal training.
• Prefer a managed, hosted solution where the vendor handles all updates and compliance.
• Your integration needs are met by popular, off-the-shelf apps.

Final Thoughts​

Beancount.io isn’t trying to be a better QuickBooks—it’s a fundamentally different way of thinking. It represents accounting as code. For technical professionals, this shift offers the same leap forward that version control with Git brought to software development: complete transparency, perfect reproducibility, and ultimate control.

At the same time, traditional accounting software continues to win on out-of-the-box ease-of-use and ready-made integrations for non-technical teams. The right choice isn't about which is "better" overall, but which is the perfect fit for your workflow, your priorities, and the degree of control you demand over your financial data.

Hello everyone! In today's blog post, we're diving into the world of Beancount, a double-entry accounting tool that's loved by many for its simplicity and power. More specifically, we're going to talk about two key concepts: Receivables and Payables.

Understanding these terms is crucial to using Beancount (or any double-entry accounting system) effectively. But don't worry if you're a beginner - we're going to break it all down, step by step!

Receivables and Payables: The Basics​

In accounting, "receivables" and "payables" are terms used to track money that is owed. "Receivables" refers to money that others owe to you, while "payables" refers to money that you owe to others.

Let's take an example:

1. Accounts Receivable (A/R): Suppose you own a bookstore and a customer buys a book on credit. The money they owe you for the book is an account receivable.

2. Accounts Payable (A/P): On the flip side, imagine you order a new set of books from a publisher, but you don't pay for them upfront. The money you owe the publisher is an account payable.

In Beancount, these are typically tracked through corresponding accounts. The main benefit here is that it provides you with a clear and accurate picture of your financial position at any point in time.

Setting Up Receivables and Payables in Beancount​

The structure of your Beancount file can be as simple or as complex as you need it to be. For receivables and payables, you'll likely want to create separate accounts under your Assets and Liabilities sections.

Here is a simple example:

1970-01-01 open Assets:AccountsReceivable
1970-01-01 open Liabilities:AccountsPayable

Tracking Transactions​

Payee side​

After setting up your accounts, you can track transactions that involve receivables and payables. Let's look at an example:

2023-05-29 * "Sold books to customer on credit"
  Assets:AccountsReceivable  100 USD
  Income:BookSales          -100 USD

Here, you're adding $100 to your receivables because a customer owes you this amount. Simultaneously, you're reducing your income by the same amount to maintain the balance (since you haven't actually received the money yet).

When the customer eventually pays, you'll record it like this:

2023-06-01 * "Received payment from customer"
  Assets:Bank:Savings        100 USD
  Assets:AccountsReceivable -100 USD

Payer side​

The same principle applies for payables, but with reversed signs:

2023-05-30 * "Bought books from publisher on credit"
  Liabilities:AccountsPayable  200 USD
  Expenses:BookPurchases     -200 USD

And when you pay off your debt:

2023-06-02 * "Paid off debt to publisher"
  Liabilities:AccountsPayable -200 USD
  Assets:Bank:Checking        200 USD

Wrapping Up​

Receivables and payables are at the heart of any accounting system. By accurately tracking these, you gain a comprehensive understanding of your financial health.

This is just a starting point, and Beancount is capable of much more. I hope this blog post helps clarify these important concepts. As always, happy accounting!

Example Account Name​

Assets:US:BofA:Checking

Account Types​

Assets          +
Liabilities     -
Income          -
Expenses        +
Equity          -

Commodities​

CNY, EUR, CAD, AUD
GOOG, AAPL, RBF1005
HOME_MAYST, AIRMILES
HOURS

Directives​

General syntax

YYYY-MM-DD <Directive> <Parameters...>

Opening & Closing Accounts​

2001-05-29 open Expenses:Restaurant
2001-05-29 open Assets:Checking     USD,EUR  ; Currency constraints

2015-04-23 close Assets:Checking

Declaring Commodities (Optional)​

1998-07-22 commodity AAPL
  name: "Apple Computer Inc."

Prices​

2015-04-30 price AAPL   125.15 CNY
2015-05-30 price AAPL   130.28 CNY

Notes​

2013-03-20 note Assets:Checking "Called to ask about rebate"

Documents​

2013-03-20 document Assets:Checking "path/to/statement.pdf"

Transactions​

2015-05-30 * "Some narration about this transaction"
  Liabilities:CreditCard   -101.23 CNY
  Expenses:Restaurant       101.23 CNY

2015-05-30 ! "Cable Co" "Phone Bill" #tag ˆlink
  id: "TW378743437"               ; Meta-data
  Expenses:Home:Phone  87.45 CNY
  Assets:Checking                 ; You may leave one amount out

Postings​

  ...    123.45 USD                             Simple
  ...        10 GOOG {502.12 USD}               With per-unit cost
  ...        10 GOOG {{5021.20 USD}}            With total cost
  ...        10 GOOG {502.12 # 9.95 USD}        With both costs
  ...   1000.00 USD   @ 1.10 CAD                With per-unit price
  ...        10 GOOG {502.12 USD} @ 1.10 CAD    With cost & price
  ...        10 GOOG {502.12 USD, 2014-05-12}   With date
  ! ...   123.45 USD ...                        With flag

Balance Assertions and Padding​

; Asserts the amount for only the given currency:
2015-06-01 balance Liabilities:CreditCard  -634.30 CNY

; Automatic insertion of transaction to fulfill the following assertion:
2015-06-01pad Assets:Checking Equity:Opening-Balances

Events​

2015-06-01 event "location" "New York, USA"
2015-06-30 event "address" "123 May Street"

Options​

option "title" "My Personal Ledger"

Other​

pushtag #trip-to-peru
...
poptag  #trip-to-peru
; Comments begin with a semi-colon

Why Modern Bookkeeping Matters​

Still managing your investments with spreadsheets? While spreadsheets are versatile, they can become cumbersome and error-prone as your investment portfolio grows. Enter Beancount.io – a sophisticated yet user-friendly investment tracking platform designed specifically for managing stock and cryptocurrency portfolios. Built with engineers and financial minimalists in mind, Beancount.io combines powerful features with an intuitive interface to streamline your investment tracking experience.

Double-entry Bookkeeping: The Foundation of Accuracy​

Beancount.io is built on the principles of double-entry accounting – a time-tested methodology used by financial institutions worldwide. This system ensures mathematical accuracy through a simple yet powerful concept: every financial transaction must balance perfectly.

In double-entry bookkeeping, each transaction requires at least two entries – a debit (+) and a credit (-) – across different accounts. This built-in verification system makes it virtually impossible to record unbalanced transactions, ensuring your financial records remain accurate and reliable.

1970-01-01 open Income:BeancountCorp
1970-01-01 open Assets:Cash
1970-01-01 open Expenses:Food
1970-01-01 open Assets:Receivables:Alice
1970-01-01 open Assets:Receivables:Bob
1970-01-01 open Assets:Receivables:Charlie
1970-01-01 open Liabilities:CreditCard

2019-05-31 * "BeancountCorp" "Salary of May 15th to May 31st"
  Income:BeancountCorp               -888 USD
  Assets:Cash                         888 USD

2019-07-12 * "Popeyes chicken sandwiches" "dinner with Alice, Bob, and Charlie"
  Expenses:Food 20 USD
  Assets:Receivables:Alice 20 USD
  Assets:Receivables:Bob 20 USD
  Assets:Receivables:Charlie 20 USD
  Liabilities:CreditCard -80 USD

As you can see in the two examples above, every transaction must fulfill the accounting equation.

Assets = Liabilities + Equity(aka Net Assets)

We used the Beancount syntax by Martin Blais and the web project Fava by Jakob Schnitzer to build this website. And it will alert you if any transaction has any legs not summing to zero.

Now you understand how we enforce the correctness of the ledger. But you may ask what are those "accounts"?

Understanding Accounts: The Water Bucket Analogy​

Think of your financial accounts as a system of interconnected water buckets, where money flows like water between them. This analogy makes double-entry bookkeeping intuitive: when you transfer money from one account to another, it's like pouring water from one bucket to another – the total amount of water (money) in the system remains constant.

Beancount.io introduces five kinds of accounts.

1. Income — Its amount is always negative or in debit. This is because you are making money, and then the money is debiting from "Income" account and crediting to your "Assets."
2. Expenses — Its amount is always positive or in credit. This is because you are spending money, and the money is flowing from the "Assets" or "Liabilities" to the "Expenses."
3. Liabilities — Its amount is positive or zero. Your credit card liabilities are a good example, which rises and falls in cycles.
4. Assets — Its amount is positive or zero. Your cash or houses are always worth some prices.
5. Equity — Your net assets. The system will calculate automatically for you. Equity = Assets - Liabilities and it reflects how wealthy you are.

Now you can open your customized accounts with those keywords above:

1970-01-01 open Assets:Cash
1970-01-01 open Assets:Stock:Robinhood
1970-01-01 open Assets:Crypto:Coinbase
1970-01-01 open Expenses:Transportation:Taxi
1970-01-01 open Equity:OpeningBalance

Advanced Investment Tracking with Commodities​

Beancount.io excels at tracking diverse investments, from stocks to cryptocurrencies. Let's explore how it handles complex investment scenarios. For example, here's how you would record purchasing 10 Bitcoins at $100 each in 2014:

2014-08-08 * "Buy 10 Bitcoin"
  Assets:Trade:Cash -1000.00 USD
  Assets:Trade:Positions  10 BTC {100.00 USD}

And then three years later, you sell them (originally with costs of $100 per unit annotated with {100.00 USD}) at the price of $10,000 per unit annotated with @ 10,000.00 USD.

2017-12-12 * "Sell 2 Bitcoin"
  Assets:Trade:Positions                   -2 BTC {100.00 USD} @ 10,000.00 USD
  Assets:Trade:Cash                          20,000.00 USD
  Income:Trade:PnL                          -19,800.00 USD

Or the same transaction with @@ 20,000.00 USD means that at the price of $20,000 in total.

2017-12-12 * "Sell 2 Bitcoin"
  Assets:Trade:Positions                   -2 BTC {100.00 USD} @@ 20,000.00 USD
  Assets:Trade:Cash                          20,000.00 USD
  Income:Trade:PnL                          -19,800.00 USD

The sum of all legs of the transaction, including -2 BTC {100.00 USD}, are still, as always, zero.

The costs {100.00 USD} tag is important because you might have bought the same commodity at different costs.

100 BTC {10.00 USD, 2012-08-08}
10 BTC {100.00 USD, 2014-08-08}

If you want to simplify the process, you can set up the account at the beginning with FIFO or LIFO. FIFO stands for first in, first out, while LIFO stands for last in, first out. In the US, IRS uses FIFO to calculate your PnL and tax accordingly.

1970-01-01 open Assets:Trade:Positions "FIFO"

And then when you sell it in shorthand like -2 BTC {}, beancount will apply FIFO strategy automatically and sell the oldest commodity.

Getting Started with Beancount.io​

Beancount.io is a modern cloud-based financial management platform that transforms your text-based transaction records into comprehensive financial statements, including income statements, balance sheets, and trial balances. By combining the reliability of plain text files with powerful visualization tools, Beancount.io helps you maintain precise control over your financial life while gaining valuable insights into your investment performance.

Start your financial journey with Beancount.io - Free during our promotional period!