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:
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 USDNotice 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 USDThe #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 USDCash 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 USDSale 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 USDExpense 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 USDPayroll (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 USDMonthly 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 USDPrepaid 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 USDUnearned 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 USDBad-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 USDPeriodic 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 USDAdjusting 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 USDNote: 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:
- Start with the date (YYYY-MM-DD) and a transaction flag (
*). - Add a payee and a descriptive narration. Use
#tagsand^linksfor searchability. - Include at least two posting lines that balance to zero for each commodity.
- Use proper account names under the five types:
Assets,Liabilities,Equity,Income,Expenses. - 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, andLiabilitiesare 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
^linksconsistently 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.