Understanding Journal Entries in Beancount

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:

Account Type	Increases With
Assets	Debit
Expenses	Debit
Liabilities	Credit
Equity	Credit
Income	Credit

---

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.

Accounting Instruction	Beancount Action
Debit an expense	Positive amount to an Expenses: account
Credit a liability	Negative amount to a Liabilities: account
Accrue revenue	Assets:AccountsReceivable + <br> Income:* -
Defer revenue	Assets:Bank:* + <br> Liabilities:Unearned:* -
Recognize deferred revenue	Liabilities:Unearned:* + <br> Income:* -

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