14 publicaciones con la etiqueta "accounting"

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.

Accrued expenses sound abstract until month-end closes start piling up. They are a cornerstone of proper accrual accounting, ensuring your financial reports reflect economic reality, not just when cash changes hands. Here’s a clear, Beancount-first walkthrough of what they are, why they matter, and exactly how to book, reverse, and report them in your plain-text ledger.

TL;DR ⚡​

• Accrued expenses are costs you’ve incurred this period but haven’t paid yet. They are recorded as a liability until the cash goes out.
• In Beancount, this is simple: you debit an Expenses: account and credit a Liabilities:Accrued: account. Later, you clear the liability when you pay.
• To report, you can see what you owe as of a specific date by running a bean-query with CLOSE ON and CLEAR to get a clean balance-sheet snapshot.

What is an Accrued Expense?​

An accrued expense is a cost that a business has incurred, but has not yet paid. It's recorded when the service is received or the cost is incurred, even if the invoice hasn't arrived or the payment isn't due yet. This practice follows the matching principle of accrual accounting, which dictates that expenses should be recorded in the same period as the revenues they helped generate.

Common examples include:

• Wages earned by employees at the end of a month but paid in the next.
• Utilities (electricity, water) you used in December but won't be billed for until January.
• Interest on a loan that has accumulated over the month but has not yet been withdrawn from your account.

By recording these costs when they happen, you get a much truer picture of your company's financial performance for that period.

How Beancount Thinks About It (in 30 seconds)​

Beancount is a plain-text, double-entry accounting system. Everything is a dated directive or transaction in a text file. The system is built on five core account types: Assets, Liabilities, Equity, Income, and Expenses.

Entries are always ordered by date. A key detail is that balance assertions are checked before same-day transactions are processed. This is important to remember when you place checks and reversing entries.

Finally, the bean-query language provides a powerful, SQL-like way to generate reports. With operators like OPEN ON, CLOSE ON, and CLEAR, you can create precise "as-of" views for financial statements.

Your Chart of Accounts (Suggested)​

A clean, hierarchical chart of accounts is your best friend. For accrued expenses, the structure is straightforward. You'll need:

• An expense account: e.g., Expenses:Utilities, Expenses:Payroll:Wages
• A corresponding liability account: e.g., Liabilities:Accrued:Utilities, Liabilities:Accrued:Payroll
• Your cash account: e.g., Assets:Bank:Checking

Beancount enforces the five top-level account types. Keeping your account names organized makes querying and reporting much easier down the road.

The Core Pattern (No Plugin, No Magic)​

This is the most direct way to handle accruals in Beancount. It involves two steps: accruing the expense at month-end and clearing the liability when you pay.

Step 1: Accrue the Expense at Month-End​

On the last day of the period, you record the expense and create the liability.

2025-02-28 * "Accrue February electricity" #accrual
  Expenses:Utilities                 120.00 USD
  Liabilities:Accrued:Utilities

Step 2: Clear the Accrual When You Pay​

When the bill comes and you pay it, you don't hit the expense account again. Instead, you debit the liability account to clear it out.

2025-03-05 * "Pay Feb electricity - City Power"
  Liabilities:Accrued:Utilities      120.00 USD
  Assets:Bank:Checking

This is the cleanest approach for small teams. It correctly places the expense in February and ensures you don't double-count it in March. Notice that in Beancount, leaving one amount blank lets the system balance the transaction for you automatically.

Alternative: Reversing Entry on Day 1​

If you prefer the classic "auto-reverse" accounting style, you can post the opposite of your accrual entry on the first day of the next month. Then, you book the actual vendor bill to the expense account as you normally would.

Step 1: Accrue at Month-End (Same as before)​

2025-02-28 * "Accrue February electricity" #accrual
  Expenses:Utilities                 120.00 USD
  Liabilities:Accrued:Utilities

Step 2: Reverse on the First Day of the Next Month​

2025-03-01 * "Reverse Feb electricity accrual" #reversal
  Liabilities:Accrued:Utilities      120.00 USD
  Expenses:Utilities

Step 3: Book the Payment as Usual​

2025-03-05 * "City Power - February bill"
  Expenses:Utilities                 120.00 USD
  Assets:Bank:Checking

Heads-up on checks: Remember that balance assertions evaluate before same-day transactions. If you want to check your Liabilities:Accrued:Utilities account balance, place the assertion on 2025-02-28 to confirm the accrual or on 2025-03-01 after the reversal transaction to confirm it's zero. Placing it before the reversal on 2025-03-01 will cause a false failure.

Six Common Accruals (Copy-Paste Patterns) 📋​

Here are some ready-to-use examples for common business accruals.

1. Rent Not Yet Invoiced​

2025-01-31 * "Accrue January rent" #accrual
  Expenses:Rent                   3000.00 USD
  Liabilities:Accrued:Rent

2. Wages Earned but Unpaid​

2025-03-31 * "Accrue March wages" #accrual
  Expenses:Payroll:Wages          8500.00 USD
  Liabilities:Accrued:Payroll

3. Vacation Pay (PTO) Earned​

2025-03-31 * "Accrue PTO earned in March" #accrual
  Expenses:Payroll:PTO             900.00 USD
  Liabilities:Accrued:Payroll

4. Interest Accrued on a Loan​

2025-02-29 * "Accrue monthly loan interest" #accrual
  Expenses:Interest                210.00 USD
  Liabilities:Accrued:Interest

5. Professional Fees (Audit/Legal)​

2025-12-31 * "Accrue year-end audit fees" #accrual
  Expenses:Professional:Audit     4200.00 USD
  Liabilities:Accrued:Professional

6. Utilities Used but Not Billed​

2025-04-30 * "Accrue April utilities" #accrual
  Expenses:Utilities                95.00 USD
  Liabilities:Accrued:Utilities

Reporting: "What do I owe as of a certain date?"​

bean-query is your tool for getting answers. Here’s how you can get a proper balance sheet snapshot of your accrued expenses.

Get All Accrued Liability Balances at Period-End​

This query gives you the balance of each accrued liability account as of March 31, 2025.

bean-query main.beancount '
  SELECT account, UNITS(SUM(position)) AS balance
  FROM OPEN ON 2025-01-01 CLOSE ON 2025-04-01 CLEAR
  WHERE account ~ "^Liabilities:Accrued"
  GROUP BY 1
  ORDER BY 1;
'

• OPEN ON sets starting balances at the period start.
• CLOSE ON truncates transactions before this date (it's exclusive). That's why we use 2025-04-01 to get data up to and including 2025-03-31.
• CLEAR zeroes out Income and Expenses, giving you a clean balance sheet view (Assets, Liabilities, Equity).

See a Register of All Accrual Postings​

If you want to see the raw transaction history for your accrual accounts:

bean-query main.beancount '
  SELECT date, payee, narration, position
  WHERE account ~ "^Liabilities:Accrued"
  ORDER BY date;
'

Get a Single Total for All Accruals​

For a quick summary of the total amount you owe:

bean-query main.beancount '
  SELECT UNITS(SUM(position)) AS total_accruals
  FROM OPEN ON 2025-01-01 CLOSE ON 2025-04-01 CLEAR
  WHERE account ~ "^Liabilities:Accrued";
'

Controls & "Gotchas" Specific to Beancount​

• Balance Assertions Timing: As mentioned, assertions check the balance at the start of the day. 2025-03-01 balance ... runs before any transactions on 2025-03-01. Plan accordingly.
• Naming and Hierarchy: A tidy tree like Liabilities:Accrued:* is not just for looks. It makes your queries simpler and your reports instantly understandable.
• Pad with Caution: The pad directive can fix opening balances, but avoid using it to "fix" recurring accruals. Making explicit entries provides a clear audit trail.
• As-Of Reporting: For balance-sheet snapshots, always prefer OPEN ... CLOSE ... CLEAR in bean-query. This prevents income and expense accounts from polluting your liability totals.

Prepaid vs. Accrued (Quick Contrast)​

It's easy to mix these up. They are mirror images:

• Accrued Expense: Service consumed now, cash paid later. This creates a liability.
• Prepaid Expense: Cash paid now, service consumed later. This creates an asset.

The accounting logic is the same in Beancount; only the accounts differ (Assets:Prepaid:* vs. Liabilities:Accrued:*).

Drop-in Template (Start of File)​

Here are the open directives you'd need for the examples used in this post. Add these to the top of your ledger file once.

; --- Accounts (open once) ---
2025-01-01 open Assets:Bank:Checking
2025-01-01 open Expenses:Utilities
2025-01-01 open Expenses:Payroll:Wages
2025-01-01 open Expenses:Interest
2025-01-01 open Expenses:Professional:Audit
2025-01-01 open Liabilities:Accrued:Utilities
2025-01-01 open Liabilities:Accrued:Payroll
2025-01-01 open Liabilities:Accrued:Interest
2025-01-01 open Liabilities:Accrued:Professional

Final Notes​

If you run your books on a cash basis, you won’t post accruals at all—expenses are simply recorded when they are paid. If you run on an accrual basis, using the patterns above is essential for matching costs to the period where you consumed the service.

The examples here provide general educational guidance. Always consult your CPA for industry-specific treatments, especially regarding bonuses, payroll taxes, and capitalization thresholds.

If you track fixed assets in your accounting—laptops, cameras, machinery, or even office furniture—your books need to reflect their declining value. This involves two key concepts: depreciation (the expense) and its running total, accumulated depreciation. This guide explains both in plain language and then shows you exactly how to model them in Beancount with copy-pasteable examples, including powerful automation options.

What is accumulated depreciation?​

Accumulated depreciation is the total amount of depreciation that has been recorded against an asset since the day it was put into service. Think of it as a running tally. It’s not a new kind of expense—it's just the to-date sum of all past depreciation charges for that asset.

In financial statements, you’ll see accumulated depreciation paired with the asset’s original price. This allows anyone reading your books to see both the historical cost (what you paid for it) and the net book value (what it's currently worth on your books).

A crucial detail is that accumulated depreciation is a contra-asset account. This might sound complex, but it's a simple idea:

• It's an "asset" account, so it lives in the Assets section of your chart of accounts.
• However, it carries a credit balance (a negative value in Beancount's asset accounts), which reduces the value of the related fixed asset.

Where does it appear on the balance sheet?​

Accumulated depreciation typically appears on the balance sheet directly underneath the fixed asset it relates to. For example:

Many financial statements simplify this by showing a single line item like “Property, plant & equipment, net”. This single number represents the total historical cost of all assets minus their total accumulated depreciation, giving you the final net book value.

How do you calculate depreciation?​

There are several methods for calculating depreciation. The one you choose determines how much expense you record each period, which in turn adds to the accumulated depreciation total. Two common families of methods are:

• Straight-Line (SL): This is the simplest and most common method for bookkeeping purposes. You expense an equal amount of the asset's value in each period of its useful life. For example, a $3,000 laptop with a 36-month (3-year) useful life would be depreciated at$83.33 per month.
• Tax Methods (e.g., MACRS in the U.S.): For tax purposes, governments often define specific accelerated schedules. In the U.S., the Modified Accelerated Cost Recovery System (MACRS) allows you to take larger depreciation deductions in the earlier years of an asset's life. Beancount can easily handle these schedules—you just need to calculate the amounts according to the official tables (like those in IRS Publication 946) and generate the corresponding journal entries.

Formula (Straight-Line)

Periodic Depreciation = $\\frac{\\text{Cost} - \\text{Salvage Value}}{\\text{Useful Life}}$

Accumulated Depreciation (at date t) = $\\sum (\\text{Periodic Depreciation up to } t)$

Salvage value is the estimated residual value of an asset at the end of its useful life. For simplicity, it's often assumed to be zero.

The Beancount Way: Model Cost and Accumulated Depreciation​

To properly track fixed assets in Beancount while preserving their original cost, you’ll use a pair of asset accounts for each category, plus an expense account.

• Assets:Equipment:Computers:Cost (to hold the historical cost)
• Assets:Equipment:Computers:AccumDep (the contra-asset, which will be credited over time)
• Expenses:Depreciation:Computers (to record the periodic expense)

This structure mirrors standard accounting practice and is the recommended approach for managing fixed-asset depreciation in Beancount.

Option A: Manual Straight-Line Entries​

This is the most direct method. You control every entry, which is great for understanding the mechanics.

1. Open the necessary accounts

2025-01-01 open Assets:Bank:Checking
2025-01-01 open Assets:Equipment:Computers:Cost
2025-01-01 open Assets:Equipment:Computers:AccumDep
2025-01-01 open Expenses:Depreciation:Computers

2. Record the purchase (at historical cost)

When you buy the asset, you debit the Cost account.

2025-01-20 * "Purchase MacBook Pro"
  Assets:Equipment:Computers:Cost      3000.00 USD
  Assets:Bank:Checking               -3000.00 USD

3. Record monthly depreciation

Each month, you'll record the depreciation expense. For a $3,000 asset over 36 months, the monthly depreciation is$3000 \div 36 = $83.33$.

The transaction involves debiting the expense account and crediting the contra-asset account.

2025-02-28 * "Monthly depreciation - MacBook Pro (SL 36mo)"
  Expenses:Depreciation:Computers           83.33 USD
  Assets:Equipment:Computers:AccumDep      -83.33 USD  ; This is the credit to the contra-asset

You would repeat this entry every month for 36 months. The balance in Assets:Equipment:Computers:AccumDep will grow more negative over time, reducing the asset's net book value.

Quick Check: You can easily check the net book value in Fava's Balance Sheet or by running a quick query:

bean-query myledger.bean "SELECT account, SUM(position) WHERE account ~ 'Assets:Equipment:Computers:(Cost|AccumDep)' GROUP BY account"

The sum of the balances of these two accounts is your net book value.

Option B: Automate with Fava’s amortize Plugin​

If you use Fava (the popular web interface for Beancount) and your depreciation is a fixed amount each month, you can automate it.

First, enable the plugin at the top of your Beancount file:

plugin "fava.plugins.amortize_over"

Next, create a single transaction that defines the entire depreciation schedule.

; 1. Record the initial purchase as usual
2025-01-20 * "Purchase MacBook Pro"
  Assets:Equipment:Computers:Cost      3000.00 USD
  Assets:Bank:Checking               -3000.00 USD

; 2. Set up the depreciation schedule
2025-01-20 * "Depreciation schedule - MacBook Pro"
  amortize_months: 36
  Expenses:Depreciation:Computers       3000.00 USD
  Assets:Equipment:Computers:AccumDep  -3000.00 USD

The plugin will see this transaction and automatically generate virtual postings for $83.33 each month for 36 months. These entries don't get written to your .bean file but appear in all reports. This is perfect for straight-line depreciation but won't work for irregular schedules like MACRS.

Option C: Generate Periodic Entries with a Third-Party Plugin​

If you prefer to have real, non-virtual transactions written into your files but still want automation, a periodic entry generator is a great choice. One of the most popular is beancount-periodic by Dallas Lu. This plugin can be configured to create dated postings on your behalf, giving you the control of manual entries with the convenience of automation.

Viewing Results: Cost, Accumulated Depreciation, and Net Book Value​

No matter which method you choose, your Balance Sheet will show both the Cost and AccumDep accounts under your Assets. The sum of these two is your net book value. This presentation—showing the gross cost less the accumulated depreciation—is exactly what accountants and financial analysts expect to see. It provides full transparency into the age and value of your assets.

Disposing of an Asset (Sell, Scrap, or Retire)​

When an asset reaches the end of its life, you either sell it, scrap it, or retire it. To remove it from your books, you must:

1. Remove its historical cost.
2. Remove its associated accumulated depreciation.
3. Record any cash received.
4. Record any resulting gain or loss (the difference between cash received and the net book value).

Example: Selling an Asset for a Gain

Let's say you sell the MacBook Pro on June 15, 2027.

• Original Cost: $3,000
• Accumulated Depreciation at time of sale: -$2,500
• Net Book Value: $3,000 -$2,500 = $500
• You sell it for: $800
• Gain on Sale: $800 (proceeds) -$500 (net book value) = $300

Here is the Beancount transaction to record the disposal:

2027-06-15 * "Sell MacBook Pro"
  Assets:Bank:Checking                     800.00 USD  ; Cash received
  Assets:Equipment:Computers:AccumDep     2500.00 USD  ; Debit to zero out the contra-asset
  Assets:Equipment:Computers:Cost        -3000.00 USD  ; Credit to remove the original cost
  Income:Gains:AssetDisposals             -300.00 USD  ; Credit to record the gain

If the proceeds had been only $400 (a loss of$100), you would post the difference to an Expenses:Losses:AssetDisposals account with a positive amount (a debit).

FAQ (Fast)​

• Is accumulated depreciation an asset or a liability? Neither. It’s a contra-asset. It's located in the assets section of your balance sheet but has a credit balance, which reduces the total asset value.

• Do I ever post directly to the Cost account after purchase? Generally, no. The purpose of the contra-asset account is to preserve the original historical cost. All reductions in value due to depreciation should be posted to ...:AccumDep.

• Can I use Beancount for MACRS (tax) schedules? Yes. You'll need to calculate the depreciation amounts for each period using the tables in IRS Publication 946. Then, you can record those amounts using manual entries or a periodic plugin. The Fava amortize plugin is not suitable for this, as MACRS amounts are not equal each month.

• What about Section 179 expensing? Section 179 allows you to expense the full cost of qualifying property in the year you place it in service, instead of depreciating it over time. This is an election you make for tax purposes. In Beancount, this would simply be a debit to an expense account instead of a fixed asset account at the time of purchase.

Common Pitfalls (and How to Avoid Them)​

• Posting depreciation directly against the Cost account.
  • Fix: Always credit the ...:AccumDep contra-asset account. This preserves the historical cost, which is important for financial reporting.
• Forgetting to remove Accumulated Depreciation on disposal.
  • Fix: When you sell or scrap an asset, your journal entry must include a debit to ...:AccumDep to clear its balance for that asset.
• Mixing up bookkeeping and tax depreciation schedules.
  • Fix: Your internal management books often use straight-line for simplicity, while your tax filings may require MACRS. Keep these purposes separate and document your policy.
• Expecting the Fava amortize plugin to handle non-equal schedules.
  • Fix: Remember that this plugin is designed only for equal monthly splits. For any other pattern, use manual postings or a more flexible periodic plugin.

Copy-Paste Template​

Here is a complete template you can adapt for your own ledger.

option "title" "My Business Ledger"
plugin "fava.plugins.amortize_over"  ; Remove if not using Fava automation

; --- Accounts ---
2025-01-01 open Assets:Bank:Checking
2025-01-01 open Assets:Equipment:Computers:Cost
2025-01-01 open Assets:Equipment:Computers:AccumDep
2025-01-01 open Expenses:Depreciation:Computers
2025-01-01 open Income:Gains:AssetDisposals
2025-01-01 open Expenses:Losses:AssetDisposals

; --- Purchase at historical cost ---
2025-01-20 * "Purchase MacBook Pro"
  Assets:Equipment:Computers:Cost      3000.00 USD
  Assets:Bank:Checking               -3000.00 USD

; --- Choose ONE depreciation approach ---

; (A) Manual monthly posting
2025-02-28 * "Monthly depreciation - MacBook Pro (SL 36mo)"
  Expenses:Depreciation:Computers           83.33 USD
  Assets:Equipment:Computers:AccumDep      -83.33 USD

; (B) Fava automation (for 36 equal monthly splits)
2025-01-20 * "Depreciation schedule - MacBook Pro"
  amortize_months: 36
  Expenses:Depreciation:Computers       3000.00 USD
  Assets:Equipment:Computers:AccumDep  -3000.00 USD

; --- Sale example (edit numbers for your actual sale) ---
2027-06-15 * "Sell MacBook Pro"
  Assets:Bank:Checking                     800.00 USD
  Assets:Equipment:Computers:AccumDep     2500.00 USD
  Assets:Equipment:Computers:Cost        -3000.00 USD
  Income:Gains:AssetDisposals             -300.00 USD

TL;DR​

• Keep asset Cost and AccumDep in separate accounts to preserve historical cost.
• Record depreciation with a debit to Expenses:Depreciation:... and a credit to Assets:...:AccumDep.
• Automate equal monthly depreciation with the Fava amortize plugin or generate dated entries with a periodic plugin.
• When disposing of an asset, you must remove both its Cost and its AccumDep from the books and record the resulting gain or loss.

Sources & Further Reading​

• Beancount.io "Amortization" Guide (Contra-asset approach, Fava plugin, examples).
• Investopedia on Depreciation vs. Accumulated Depreciation (Credit balance rationale).
• IRS Publication 946 (Official rules for MACRS and U.S. tax depreciation).
• beancount-periodic Plugin (Tool for generating periodic transactions).

Selling on Amazon is a powerful way to reach millions of customers, but the platform's fee structure can feel like a maze. If you're an operator who values clean, auditable, double-entry books, tracking these costs accurately is non-negotiable. This guide breaks down Amazon's 2025 US marketplace fees and shows you exactly how to record them using the plain-text accounting tool, Beancount.

TL;DR ⚡​

• You’ll encounter a handful of recurring Amazon charges: Selling plan, Referral, Closing (media), FBA fulfillment & storage, Inbound placement, Low‑inventory‑level, Returns processing, Refund administration, and a High‑volume listing fee for very large catalogs.
• Keep a separate Assets:Amazon:Clearing account. Book sales and fees there; when Amazon pays out, transfer the net to your bank. This makes reconciliation a breeze.
• Track each SKU as its own commodity (e.g., SKU:WATER-BOTTLE) so Beancount can compute your Cost of Goods Sold (COGS) by lot automatically.
• You can reconcile quickly by importing settlement or date-range reports and mapping Amazon’s “transaction types” directly to your Beancount expense accounts.

The Amazon Fee Map (US Marketplace)​

Here’s a breakdown of the most common fees you'll see in 2025.

Selling Plan Fee​

This is your basic subscription fee for accessing the marketplace.

• Individual Plan: No monthly fee. Instead, you pay $0.99 for each item you sell.
• Professional Plan: A flat $39.99 per month, which waives the per-item charge. This is the standard choice for any serious seller. All other selling fees apply on top of this.

Referral Fee​

This is Amazon's commission for each sale.

It's a percentage of the item’s total sales price (including shipping and any gift wrapping). The rate depends entirely on the product category. Most categories fall in the 8–15% band, but some use tiered rates (e.g., 15% on the first $500 and 8% on the portion above that). Certain categories also have a minimum referral fee, often $0.30. Always check the current rate card for your specific category.

Closing Fee (Media Categories)​

If you sell media items like Books, Music, Video, or DVDs, Amazon charges an additional flat $1.80 per-item closing fee.

FBA Fulfillment Fees​

These are the per-unit pick, pack, and ship fees for using Fulfillment by Amazon (FBA). The cost varies based on the item's size and weight. Amazon updates these rate cards periodically. For 2025, non-peak rates reverted to 2024 non-peak levels on January 15, 2025. Always consult the current FBA rate card to find your product's exact size tier and associated fee.

Monthly Storage & Aged-Inventory Surcharge (FBA)​

Amazon charges for the space your inventory occupies in their fulfillment centers.

• Monthly Storage: Billed by the cubic foot.
• Aged-Inventory Surcharge: An additional monthly fee assessed on inventory that has been sitting in a fulfillment center for too long. This stacks on top of the regular monthly storage fee.

Inbound Placement Service Fee (FBA)​

This is a per-unit fee tied to how you send inventory to Amazon. It's designed to cover the costs of Amazon distributing your products across its fulfillment network. Certain programs, like "New Selection," may temporarily exempt new products up to set limits.

Low-Inventory-Level Fee (FBA)​

This fee applies to standard-size products with consistently low inventory levels relative to customer demand. Amazon measures this with a metric called "historical days of supply." If your stock level for a popular item drops below the threshold (generally 28 days), this fee kicks in.

Returns Processing Fee (FBA)​

For products in categories with higher-than-typical return rates (like apparel and shoes), Amazon can charge a returns processing fee on each customer return. Some "New Selection" units are waived from this fee up to a certain cap.

Refund Administration Fee​

When you issue a customer a refund for an order, Amazon gives you back the referral fee you paid. However, they keep a portion of it as a processing fee. This is the lesser of $5.00 or 20% of the referral fee for that item.

High-Volume Listing Fee (Huge Catalogs)​

This fee only affects sellers with massive catalogs. If you have more than 1.5 million active SKUs, Amazon charges a monthly fee of $0.001 per eligible SKU above that threshold.

Note: Rates and policies can differ by country, region, and category. Always review your local Seller Central help pages before booking.

How These Fees Show Up in Your Reports 🧾​

You can find all this data in Seller Central. The two most useful reports for accounting are:

1. Date Range Reports (Payments → Date Range Reports): These provide a summary of your income, expenses, taxes, and net transfers for a specific period. They are perfect for high-level ledger import and reconciliation.
2. Settlement Files (e.g., Flat File V2): These files break down every single transaction, showing the fee type, order ID, amount, and date. This is the granular data you'll use to map everything correctly.

A Beancount-First Way to Record Amazon Activity​

Here’s how to translate Amazon's complex world into clean, simple Beancount entries.

1. Set Up a Minimal Chart of Accounts​

First, define the accounts you'll need. This simple structure covers everything.

; --- ASSETS ---
Assets:Amazon:Clearing        ; Your Amazon "wallet"
Assets:Bank:Checking          ; Where payouts land
Assets:Inventory:SKU:<code>    ; One sub-account per SKU

; --- INCOME & COGS ---
Income:Sales:Amazon
Expenses:COGS:Inventory

; --- EXPENSES ---
Expenses:Marketplace:Amazon:Referral
Expenses:Marketplace:Amazon:FBAFulfillment
Expenses:Marketplace:Amazon:Storage:Monthly
Expenses:Marketplace:Amazon:Storage:Aged
Expenses:Marketplace:Amazon:InboundPlacement
Expenses:Marketplace:Amazon:LowInventoryLevel
Expenses:Marketplace:Amazon:ReturnsProcessing
Expenses:Marketplace:Amazon:Other ; For misc. fees

Beancount’s ability to track inventory lots and cost basis is a superpower. You'll "buy" inventory into Assets:Inventory:SKU:... with a cost {...}. When you sell, Beancount automatically calculates the Cost of Goods Sold.

2. Book Each Sale and Its Fees​

Let's record a $30 FBA sale for SKU:WATER-BOTTLE. The referral fee is $4.50, FBA fulfillment is $4.24, and you incurred a $0.15 low-inventory fee. You originally purchased this unit for $5.00.

2025-02-10 * "Amazon Order 113-2233445-6677889" "WATER-BOTTLE"
  Assets:Amazon:Clearing                         21.11 USD
  Income:Sales:Amazon                           -30.00 USD
  Expenses:Marketplace:Amazon:Referral            4.50 USD
  Expenses:Marketplace:Amazon:FBAFulfillment      4.24 USD
  Expenses:Marketplace:Amazon:LowInventoryLevel   0.15 USD
  Assets:Inventory:SKU:WATER-BOTTLE              -1 SKU:WATER-BOTTLE {5.00 USD}
  Expenses:COGS:Inventory                         5.00 USD

Why it balances: The $30 sale is credited to Income. The fees ($4.50 + $4.24 + $0.15) and the COGS ($5.00) are debited to your expense accounts. The net cash from the sale, $21.11, is debited to your Assets:Amazon:Clearing account. The inventory asset is credited (reduced by one unit), and the corresponding cost is expensed.

3. Record the Payout​

When Amazon disburses your funds, the transaction is simple. You're just moving money from your Amazon "wallet" to your actual bank account.

2025-02-15 * "Amazon Payments" "Settlement disbursement"
  Assets:Bank:Checking                    2,500.00 USD
  Assets:Amazon:Clearing                -2,500.00 USD

After each payout, your Assets:Amazon:Clearing account balance should trend back toward zero. Use your date-range report totals to spot any discrepancies.

4. Handle Storage, Aged Inventory, and Inbound Placement​

These fees often appear as separate lines in your settlement reports. Book them as direct debits to your clearing account.

2025-03-15 * "Amazon FBA Storage Fees" "Monthly + aged inventory"
  Expenses:Marketplace:Amazon:Storage:Monthly    125.40 USD
  Expenses:Marketplace:Amazon:Storage:Aged        35.20 USD
  Assets:Amazon:Clearing                        -160.60 USD

2025-03-20 * "FBA Inbound Placement Service" "Shipment split optimization"
  Expenses:Marketplace:Amazon:InboundPlacement    62.00 USD
  Assets:Amazon:Clearing                         -62.00 USD

5. Refunds & Returns​

When a customer returns a product, you reverse the sale and the COGS, and account for any non-refundable fees. For this $30 sale, let's say Amazon keeps a $0.30 refund administration fee.

2025-03-02 * "Refund 113-2233445-6677889" "Refunded WATER-BOTTLE"
  Assets:Amazon:Clearing                       -29.70 USD  ; Net debit
  Income:Sales:Amazon                           30.00 USD  ; Reverse the sale
  Expenses:Marketplace:Amazon:Other              0.30 USD  ; The refund admin fee
  Assets:Inventory:SKU:WATER-BOTTLE              1 SKU:WATER-BOTTLE {5.00 USD}
  Expenses:COGS:Inventory                       -5.00 USD  ; Reverse the COGS

Here, you debit Income to reverse the revenue, and credit Expenses:COGS to reverse the cost. The inventory unit is added back to your asset account. The net effect on your Assets:Amazon:Clearing is the amount refunded to the customer.

Importing & Reconciling Quickly​

The key to efficiency is mapping. Export a Date Range Report or a Flat File V2 settlement report from Seller Central. Then, create a simple mapping from Amazon's transaction-type column to your expense accounts:

• Order → Income:Sales:Amazon
• Commission → Expenses:Marketplace:Amazon:Referral
• FBA-fulfillment-fee → Expenses:Marketplace:Amazon:FBAFulfillment
• StorageFee → Expenses:Marketplace:Amazon:Storage:Monthly
• AgedInventorySurcharge → Expenses:Marketplace:Amazon:Storage:Aged
• InboundPlacementFee → Expenses:Marketplace:Amazon:InboundPlacement
• LowInventoryLevelFee → Expenses:Marketplace:Amazon:LowInventoryLevel

For those looking to automate, Beancount’s import ecosystem (like beancount-import) is fantastic. You define the rules once, and your settlement files can be ingested into your ledger automatically.

Practical Guardrails That Save Money (and Keystrokes) 💰​

• Avoid the Low-Inventory Fee: Watch your historical days of supply. Keep enough buffer stock to meet demand, but don't overdo it and trigger aged-inventory surcharges.
• Use New Selection Benefits: When launching new products, enroll them in the New Selection program to get temporary waivers on returns processing and inbound placement fees.
• Check Referral Rates Before Pricing: A small price change could push you over a fee threshold, significantly impacting your net margin. Confirm your category's referral rates and minimums.
• Reconcile Monthly: Pull a Date Range Report every month. This simple habit helps you catch any fee changes from Amazon early and ensures your ledger remains trustworthy.

Ready-to-Use Beancount Template​

To help you get started, I've prepared a starter ledger file. It includes:

• A sensible Amazon chart of accounts.
• Inventory configured as commodities for automatic, lot-based COGS.
• Example entries for sales, fees, storage, refunds, and payouts.

➡️ Download the Template (Open the file in your editor, replace the sample SKU and amounts, and start importing settlement lines.)

References & Further Reading​

• Selling Plans & Fees Overview: Sell on Amazon
• Professional Plan Monthly Fee: Seller Central
• Referral Fee Rates: Seller Central
• 2025 FBA Fulfillment Fees: Seller Central
• Aged-Inventory Surcharge: Seller Central
• Inbound Placement Service Fee: Seller Central
• Low-Inventory-Level Fee: Seller Central
• Returns Processing Fee: Seller Central
• Refund Administration Fee: Seller Central
• High-Volume Listing Fee: Seller Central
• Date Range Reports: Seller Central
• Beancount Inventories & Costing: Beancount Docs

One Last Tip​

If you sell internationally, create marketplace-specific sub-accounts (e.g., Expenses:Marketplace:Amazon:Referral:US, ...:Referral:CA). Set your main operating_currency in Beancount to your home currency. Once your data is structured, Beancount's query language makes it trivial to analyze your fee mix by marketplace, category, or SKU.

Happy booking!

Accounts payable (AP) is the money your business owes to its suppliers for goods or services you’ve already received but haven't paid for yet. In the world of accounting, AP is classified as a current liability on your balance sheet—an amount typically due within the next year, and often within 30 to 60 days.

This concept is central to accrual accounting, where you record the expense and the corresponding liability the moment a bill arrives, not when you actually send the cash. This guide will show you how to manage the entire AP workflow cleanly and efficiently using the plain-text accounting tool, Beancount.

Quick Summary​

Before we dive into the details, let's cover the essentials:

• Accounts Payable (AP) represents your short-term debts to vendors. You'll find it under the Liabilities section of your balance sheet.
• Accrual vs. Cash: AP is a concept that exists only if you keep your books on an accrual basis. Beancount fully supports accrual workflows, and its web interface, Fava, will display your liabilities correctly.
• AP vs. AR: It's simple: Payables are what you owe, while Receivables (AR) are what others owe you.

Where AP Lives in Beancount (and Fava)​

To start tracking AP, you first need to declare an account for it in your ledger. A standard convention is:

Liabilities:AccountsPayable

You can optionally create subaccounts for major vendors (e.g., Liabilities:AccountsPayable:ForestPaintSupply).

In Fava, this account will appear on your Balance Sheet under Liabilities. You can click on it to drill down and see a list of all open and paid items, giving you a clear view of your obligations. You can even see this in action in Fava's public example ledger, which includes a Liabilities:AccountsPayable account.

Beancount Building Blocks You’ll Use​

A robust AP workflow in Beancount relies on a few core features:

1. Accounts: You'll primarily use your Liabilities:AccountsPayable account, a cash account like Assets:Bank:Checking, and your various expense accounts (e.g., Expenses:Supplies).
2. Metadata: You can attach key-value data to any transaction. For AP, you'll use metadata like invoice:, due:, terms:, and document:. Fava even recognizes the document: key and will automatically create a clickable link to the attached file if you configure a documents folder.
3. Tags & Links: Use #tags (like #ap) for easy filtering and ^links (like ^INV-10455) to programmatically tie a bill and its subsequent payment together. This creates a clear, auditable trail.
4. Queries (BQL): Beancount's SQL-like query language (BQL) allows you to run powerful reports, like listing all open payables sorted by due date, directly from the command line with bean-query or on Fava's "Query" page.

Core AP Workflow in Beancount​

Managing AP in your ledger involves two or three key steps: recording the bill, paying it, and sometimes handling partial payments or discounts.

1) Record the Vendor Bill (This Creates the Liability)​

First, you book the expense and create the payable when the invoice arrives.

; Optionally set your documents folder in your main Beancount file:
option "documents" "documents"

2025-08-05 * "Forest Paint Supply" "Paint order INV-10455" ^INV-10455 #ap
  invoice: "INV-10455"
  due: "2025-09-04"
  terms: "2/10, n/30"
  document: "invoices/2025-08-05-forest-paint-INV-10455.pdf"
  Expenses:Supplies:Paint         500.00 USD
  Liabilities:AccountsPayable    -500.00 USD

This single entry accomplishes two critical things:

1. It immediately recognizes the $500 expense in the correct period (August).
2. It creates a corresponding $500 liability, showing that you owe money to Forest Paint Supply.

The ^INV-10455 link is a unique identifier that lets you attach the same link to the payment later, keeping the bill and payment transactions logically connected.

2) Pay the Bill (This Clears the Liability)​

When you pay the invoice, you create a transaction that moves money from your bank account to clear the liability.

a) Standard Payment (No Discount):

2025-09-01 * "Forest Paint Supply" "Payment INV-10455" ^INV-10455
  Liabilities:AccountsPayable     500.00 USD
  Assets:Bank:Checking           -500.00 USD

This entry reduces your AP balance by $500 and your checking account balance by the same amount. The liability is now cleared.

b) Early-Payment Discount (e.g., "2/10, n/30"):

If the terms are "2/10, n/30", you can take a 2% discount if you pay within 10 days. For our $500 invoice, that's a$10 discount. Here are two acceptable ways to record it—just pick one method and be consistent.

; Option 1: Record the discount as other income (a contra-expense effect)
2025-08-12 * "Forest Paint Supply" "Early payment discount INV-10455" ^INV-10455
  Liabilities:AccountsPayable     500.00 USD
  Assets:Bank:Checking           -490.00 USD
  Income:Discounts:Payables       -10.00 USD

; Option 2: Reduce the original expense directly
2025-08-12 * "Forest Paint Supply" "Early payment discount INV-10455" ^INV-10455
  Liabilities:AccountsPayable     500.00 USD
  Assets:Bank:Checking           -490.00 USD
  Expenses:Supplies:Paint         -10.00 USD

In both cases, you clear the full $500 liability, reduce your bank balance by the$490 you actually paid, and account for the $10 benefit.

3) Handling Partial Payments​

Beancount's linking feature makes tracking partial payments simple and clean.

; Invoice for $1,200
2025-08-10 * "Acme Parts" "INV-9001" ^INV-9001
  invoice: "INV-9001"
  due: "2025-09-09"
  Expenses:Parts                 1200.00 USD
  Liabilities:AccountsPayable   -1200.00 USD

; First payment of $400
2025-08-20 * "Acme Parts" "Payment INV-9001 (1/3)" ^INV-9001
  Liabilities:AccountsPayable     400.00 USD
  Assets:Bank:Checking           -400.00 USD

; Final payment of $800
2025-09-05 * "Acme Parts" "Payment INV-9001 (final)" ^INV-9001
  Liabilities:AccountsPayable     800.00 USD
  Assets:Bank:Checking           -800.00 USD

By using the ^INV-9001 link on all three transactions, you can easily filter your journal to see the complete history of this specific bill and its associated payments.

Helpful Queries (BQL)​

You can run these queries in Fava’s “Query” tab or from the command line with bean-query.

Tip: The any_meta() function is incredibly useful for pulling metadata fields like invoice: and document: into your query results.

Open AP by Vendor (Balance View):

This query sums up the current outstanding balance you owe to each supplier.

SELECT payee, COST(SUM(position)) AS amount
WHERE account ~ "^Liabilities:AccountsPayable"
GROUP BY payee
ORDER BY payee;

Open AP by Invoice + Due Date:

Get a tidy list of every open bill, sorted by its due date, to help you prioritize payments.

SELECT payee,
       any_meta('invoice') AS invoice,
       any_meta('due')     AS due,
       COST(SUM(position)) AS amount
WHERE account ~ "^Liabilities:AccountsPayable"
GROUP BY payee, invoice, due
ORDER BY due, payee;

List Bills with Attached PDFs:

This query finds all your bills and shows the path to the linked document.

SELECT date, payee, any_meta('invoice') AS invoice, any_meta('document') AS file
WHERE account ~ "^Liabilities:AccountsPayable"
ORDER BY date DESC;

Where to See AP in Fava​

• Balance Sheet: Navigate to Balance Sheet → Liabilities → AccountsPayable to see the total balance and drill down into the transaction details.
• Journal: Filter the journal by account:Liabilities:AccountsPayable or a specific link like ^INV-xxxx to see a bill's complete lifecycle.
• Documents Sidebar: If you use the document: metadata and set the option "documents" directive, you'll see a list of linked documents in the sidebar.

AP Aging, Turnover, and Cash-Flow Awareness​

• Aging Schedule: This report groups your open invoices by how long they’ve been outstanding (e.g., 1–30 days, 31–60 days, 60+ days). In Beancount, the most practical approach is to run the "Open AP by Invoice + Due Date" query above, export the results as a CSV, and bucket them in a spreadsheet or a small Python script.
• AP Turnover Ratio: This is a quick health check on how fast you pay your vendors. The formula is Total Supplier Purchases ÷ Average AP. A related metric, Days Payable Outstanding (DPO), is roughly 365 ÷ Turnover Ratio.
• If You Can’t Pay on Time: AP is meant for short-term debt. If a vendor agrees to formal, longer-term repayment, you should reclassify the debt out of AP and into a note payable.

2025-10-01 * "Helix Industries" "Convert overdue AP to 12-month note" ^INV-1110
  Liabilities:AccountsPayable    2000.00 USD
  Liabilities:NotesPayable      -2000.00 USD

Best Practices for AP in a Plain-Text Ledger​

• Go Paperless: Store invoice PDFs in your documents folder and link them with the document: metadata key.
• Use Links Consistently: Put the unique invoice number in a ^link on both the bill and all associated payment entries.
• Keep Metadata Tidy: Consistently using invoice:, due:, and terms: improves search, queries, and financial reviews.
• Accrual All the Way: If you want useful AP reporting, commit to keeping your books on an accrual basis. Beancount and Fava handle this beautifully.

Copy-Paste Starter: Vendor Bill + Payment​

; ---- Bill ----
2025-08-05 * "Forest Paint Supply" "Paint order INV-10455" ^INV-10455 #ap
  invoice: "INV-10455"
  due: "2025-09-04"
  document: "invoices/2025-08-05-forest-paint-INV-10455.pdf"
  Expenses:Supplies:Paint         500.00 USD
  Liabilities:AccountsPayable    -500.00 USD

; ---- Payment (no discount) ----
2025-09-01 * "Forest Paint Supply" "Payment INV-10455" ^INV-10455
  Liabilities:AccountsPayable     500.00 USD
  Assets:Bank:Checking           -500.00 USD

This guide is for educational purposes and does not constitute tax, legal, or financial advice.

References & Further Reading:​

• Beancount documentation on core account types, tags/links, and its query language
• Fava/Beancount notes on accrual accounting and linking documents
• Using any_meta() for querying metadata fields

If your ledger lives in plain text, you already value clarity, control, and reproducibility. Outsourcing your accounting doesn’t have to compromise any of that. On the contrary, when done right, it transforms your Beancount setup into a reliable, documented workflow run by specialists—while you retain full ownership of the data, the repository, and the rules.

This is a practical guide for Beancount users on what to outsource, what to keep in-house, how to structure deliverables, and how to evaluate providers. It’s about delegating the mechanical work without ever giving up control.

Who This Is For​

This guide is for you if you fit one of these profiles:

• Solo founders, indie hackers, and consultants who use Beancount and want to reclaim time spent on the mechanical parts of accounting to focus on building your product or serving clients.
• Finance-savvy engineers who demand tight controls, versioned history, and full auditability but don't want to spend their weekends importing bank statements and reconciling accounts themselves.
• Organizations migrating from an all-in-one vendor who are now prioritizing data custody and reproducibility. Recent, abrupt shutdowns of accounting platforms like Bench have underscored a critical lesson: exit plans and open formats are not optional. (TechCrunch, KSV Advisory Report)

Beancount, Briefly​

For the uninitiated, the Beancount ecosystem is built on a few core components that make it powerful for this kind of workflow:

• Beancount: At its heart, it's a double-entry accounting language specified in plain text. You write human-readable ledger files, commit them to a Git repository, and use a compiler to validate them and generate financial reports. (GitHub)
• Fava: This is the elegant web interface for Beancount. Fava reads your ledger file and gives you interactive balance sheets, income statements, trends, filters, and a powerful SQL-like query language to inspect your data. (Fava Demo)
• beangulp: The modern framework for automating data ingestion. Evolved from Beancount's original importer, beangulp provides the tools to write robust importers that can parse CSV, OFX, QFX, and even PDF statements, turning raw bank data into structured Beancount entries. (GitHub)

A successful outsourcing relationship should preserve and enhance these strengths: version control, a human-readable history, strict validation, and the composability of your tools.

What to Outsource vs. What to Keep​

The key to effective delegation is a clear division of labor. Here’s how to draw the line between tactical execution and strategic ownership.

Great Candidates to Outsource​

These tasks are typically repetitive, rule-based, and time-consuming—perfect for a specialist.

• Statement Collection & Importing: Downloading monthly statements, normalizing various file formats (CSV, OFX, PDF), and running your beangulp importers. This includes maintaining the importer rules as financial institutions inevitably change their statement formats.
• Categorization Assistance: Building heuristics and declarative rules to categorize transactions. They can optionally use tools like smart_importer to predict postings based on historical data, but the final review always remains with a human.
• Reconciliation & Integrity Checks: The meticulous work of posting balance assertions to match your statements, investigating discrepancies, and ensuring the ledger remains error-free.
• Attachments & Document Hygiene: Fetching invoices and receipts, linking them to transactions with metadata, and archiving the source documents in a tidy, reproducible directory tree.
• Month-End Close & Reporting: Preparing the standard suite of reports (P&L, Balance Sheet, Statement of Cash Flows) and providing Fava views or exports for your management updates.
• AR/AP Ops & Payroll Prep: Preparing bills for payment, generating invoices, chasing collections, and staging payroll files for your final review and approval.
• Tax Package Prep: At the end of the year, producing a clean trial balance, supporting schedules, and all the necessary files for your CPA or tax advisor.

Keep In-House (You Own the Intent and Risk)​

These responsibilities are strategic and define the financial backbone of your business. They belong to you.

• Chart of Accounts Design: The structure and naming conventions of your accounts reflect how you think about your business. This is your financial map.
• Core Accounting Policies: Decisions on entity structure, revenue recognition, and capitalization policies have long-term financial and legal implications.
• Final Approvals: You must retain the final say on all cash movements, including payments, payroll runs, and significant journal entries.
• Strategic Finance: Forecasting, budgeting, and defining what "good" looks like for your business are fundamental owner responsibilities.

The Beancount-Native Outsourcing Workflow​

Here’s what a structured, Git-based collaboration looks like in practice.

1) Repository Layout (Example)​

Your repository is the single source of truth. A well-organized structure makes the process transparent and maintainable.

/ledger
  main.beancount        # Main ledger file, includes others
  accounts/             # Chart of Accounts definition
  includes/             # Monthly or yearly transaction files
  prices/               # Price directives for commodities/stocks
  metadata/             # Custom metadata declarations
  plugins/              # Custom Beancount plugins
  documents/            # Bank statements, receipts, invoices
/importers              # beangulp importers + rules
  config.yaml
  bank_x.py
  card_y.py
/scripts
  import.sh             # Orchestration script for importers
  close_month.py        # Month-end validation and reporting script
/reports
  monthly/
  year_end/
/ops
  runbook.md            # How to run the system
  checklist.md          # Procedural checklists (e.g., month-end)
  controls.md           # Documentation of financial controls

2) The Weekly Cycle​

Routine work should follow a predictable rhythm, culminating in a clear deliverable for your review.

1. Ingest: Your provider pulls statements and runs the beangulp importers to stage new transactions.
2. Categorize: They apply categorization rules and, if used, smart_importer suggestions. This is followed by a human review to correct any ambiguities.
3. Reconcile: They add balance assertions to match statement totals and investigate any differences. The use of pad directives should be rare and always require a clear explanation.
4. Document: Relevant documents (receipts, invoices) are attached to transactions.
5. Commit & Propose: The changes are committed with descriptive messages and a pull request is opened for your review, allowing you to see the exact diff of what changed in your books.

3) The Month-End Close (Minimum Viable)​

Closing the books is a critical checkpoint to ensure accuracy and produce reliable reports.

• Update price directives for any foreign currency or market-based securities.
• Review outstanding items: accounts receivable, accounts payable, accruals, prepaid expenses, and loans.
• Validate that all balance assertions pass and there are no other failing checks.
• Tag the commit with the closing period (e.g., 2025-08-close) and export the standard reports.
• Publish a Fava snapshot or provide a secure URL for the period.

4) The Year-End Package​

The culmination of the year's work is a tidy, auditable package for your tax preparer. This includes a final trial balance, supporting schedules for key accounts (like fixed assets or inventory), and a reproducible script to regenerate every artifact directly from the Git repository.

Security & Access (Non-Negotiables)​

A professional workflow prioritizes security and your ownership of the data.

• Data Custody First: You own the private Git repository. Your provider should work from a fork and submit pull requests. They should never host the only copy of your ledger.
• Bank Access: Provide read-only access whenever possible. If you must use an aggregator service, create isolated credentials and have a clear process for revoking them.
• Secrets & Encryption: Use tools like GPG or age to encrypt sensitive documents at rest. Enforce multi-factor authentication on all services. Operate on the principle of least privilege.
• Fava Access: You should self-host Fava or run it locally (fava ledger.beancount) and share access for review sessions via a secure tunnel or VPN. Avoid exposing it directly to the public internet.
• Exit Plan: Insist on a "pull the cord" playbook. This should include escrow or guaranteed handoff of all scripts, configurations, and documentation. As recent events show, vendors can disappear overnight; your financial records must not be stranded with them.

What “Good” Deliverables Look Like (Every Month)​

At the end of each month, you should receive two things: a technical artifact and a business summary.

1. A Clean Pull Request Containing:

• All imported and reviewed transactions for the period.
• A diff of any new or modified importer rules.
• Commit messages that summarize key assumptions or manual adjustments.
• A 100% green status on all balance assertions, with a log showing each account has been reconciled.
• Links in the Beancount file to all attached documents, plus a report of any missing documents.
• Updated price directives for investments or foreign currencies.

2. A Management Pack Containing:

• Standard reports: P&L, Balance Sheet, and Statement of Cash Flows.
• Key metrics like cash runway and budget vs. actual variance highlights.
• Direct links to pre-filtered Fava views for deeper, interactive analysis.

Provider Types (And When They Fit)​

Not all providers are the same. Match the provider to your stage and complexity.

• Beancount-Savvy Bookkeeper: Perfect for handling the core workflow: steady importing, categorization, reconciliations, and preparing month-end report packs.
• Boutique Accounting Firm: A good fit if you need additional services like managing AR/AP, payroll coordination, multi-entity consolidation, or tax preparation support.
• Fractional Controller/CFO: The right choice when you need strategic oversight. They help design accounting policies, build financial forecasts, prepare board-ready reporting, and design internal controls.

Engagements are typically structured with a monthly retainer for routine work and an hourly rate for ad-hoc projects.

Interview Questions for Beancount Outsourcing​

When vetting a potential provider, ask specific, technical questions to gauge their expertise.

• Which beangulp importers have you personally built or maintained? Can you show me anonymized examples?
• Will you deliver reproducible scripts and a runbook, or just the final output files?
• How do you enforce data integrity in your process? (Look for answers involving balance assertions, review checklists, and maybe even CI/CD linting).
• Do you use smart_importer? If so, what is your process for reviewing and overriding its predictions?
• How do you propose we structure the Git workflow (e.g., branching strategy, PR templates, commit message conventions)?
• What is your exit plan? What does the data handback process look like to ensure there is zero lock-in?
• How do you run Fava in a secure way for client review sessions?

A Simple Statement of Work (SoW) You Can Copy-Paste​

Use this as a starting point for your engagement agreement.

Scope of Work

- Weekly transaction imports via beangulp; includes rules maintenance for all connected financial institutions.
- Human-reviewed transaction categorization. Use of smart_importer for suggestions is permitted, but entries will not be auto-committed without review.
- Weekly reconciliations against statements, enforced with `balance` assertions. Variance notes will be provided for any unreconciled differences greater than $X.
- Document collection for all significant transactions; attachment hygiene and a monthly missing-documents report.
- Month-end close process, including price updates, accruals checklist, and delivery of Fava report links.
- Year-end package preparation, including a trial balance and supporting schedules for CPA review.

Deliverables

- A monthly pull request tagged "<YYYY-MM>-close" with all checks passing.
- Updates to the `/ops` folder, including diffs for `runbook.md` and `controls.md`.
- Final reports archived in `/reports/monthly` with a summary changelog.

Access & Security

- All work will be performed in the client-owned private Git repository. Vendor access is granted via a dedicated user, and all changes will be submitted via pull requests.
- Credentials will be scoped to read-only access where possible. Multi-factor authentication is required on all shared services.
- Sensitive documents will be stored using client-provided encryption keys and will be purged from vendor systems upon termination.

SLA & Cadence

- A weekly PR with reconciled transactions will be submitted every <Day of Week>.
- The month-end closing PR will be submitted by business day <N> of the following month.
- Standard response time for inquiries is <X> business hours; critical issue response is <Y> hours.

Exit Clause

- Upon termination, the vendor will hand back the complete repository, all scripts, documentation, and a map of all credentials used within <Z> business days. A 2-hour turnover call is included.

Tips That Save Hours (And Future Pain)​

• Name accounts for reconciliation. Structure your account names to include the institution and the last four digits of the account number (e.g., Assets:Bank:Chase:Checking:1234). This makes debugging trivial.
• Assert balances at statement boundaries. Treat each bank statement as a verifiable checkpoint. A balance directive at the end of each statement period ensures errors are caught early and contained.
• Automate price updates. Use Beancount's tools to fetch market prices automatically and record them with price directives. This is essential for accurate investment and foreign exchange reporting.
• Keep rules declarative. Favor writing small, testable beangulp importers over building complex, ad-hoc scripts. Declarative rules are easier to maintain and debug.
• Review with Fava, approve in Git. Use Fava's powerful interface to explore the changes and understand their impact. But the final approval happens by reviewing the diff in a Git pull request. Never let your books become a "black box."

Frequently Used Tools in This Stack​

• Beancount: Core engine and language documentation. (Docs)
• beangulp: The standard for building importers. (GitHub)
• smart_importer: Machine learning-aided predictions for categorization. (GitHub)
• Fava: The indispensable web interface for visualizing your ledger. (Website)

The Bottom Line​

Outsourcing for Beancount users isn’t about “giving up control.” It is the opposite. It’s about codifying your financial processes so that a specialist can execute them reliably on your behalf. You keep the repository, the scripts, the assertions, and the fundamental ability to regenerate any report from scratch. You delegate the work, not the ownership.

Whether you’re running a side hustle from your laptop or scaling a fast-growing startup, you have a few reliable paths to keeping clean, accurate books. But which one is right for you? The best solution depends on your budget, your technical comfort, and how much control you want over your financial data.

Here’s a clear-eyed guide to the seven most common accounting options—what they’re good at, where they struggle, and when a modern solution like Beancount.io is the perfect fit.

1) Excel​

This is often the first stop on the accounting journey for its sheer simplicity and universal availability.

• Good for: Builders and DIY founders who love total control and already know their way around a spreadsheet.
• Pros: The barrier to entry is practically zero, and thousands of free templates are available online. Its flexibility allows you to build custom financial models and track unique workflows that off-the-shelf software can't handle.
• Cons: The biggest drawback is the immense manual workload. Every transaction must be entered and reconciled by hand, which is a massive time sink. Worse, it’s dangerously easy to introduce silent formula errors or typos with no guardrails to catch them. Collaboration and maintaining a clear audit trail are clunky without rigorous discipline.
• Best if… you want a quick, no-frills start for a very simple business and you are exceptionally meticulous.

2) Google Sheets​

The cloud-native cousin of Excel, Google Sheets offers the same core functionality with a collaborative twist.

• Good for: Teams that need simple, shared spreadsheets for tracking income and expenses.
• Pros: Built-in cloud backups and dead-simple sharing are the main advantages. You can work from any device with a web browser, making it accessible for teams on the go.
• Cons: It suffers from the same fundamental flaws as Excel: a heavy manual workload and a high risk of user error. You may also run into compatibility quirks with certain templates and add-ons designed for the Microsoft ecosystem.
• Best if… your team already runs on Google Workspace and you’re willing to accept the trade-offs of a manual system.

3) QuickBooks Online​

For decades, QuickBooks has been the default choice for small businesses looking for dedicated accounting software.

• Good for: Small businesses that want a "classic" SMB software experience with a large ecosystem of integrations.
• Pros: Its signature feature is bank feeds, which automatically pull in transactions from your bank and credit card accounts, drastically reducing manual data entry. It provides a wide range of financial reports out of the box and is supported by a massive community of accountants and app developers.
• Cons: While transactions are imported automatically, the system still requires your weekly attention to categorize expenses and reconcile accounts correctly. The interface can have a steep learning curve, and the cost can grow with add-on features. Most importantly, it creates vendor lock-in, making it difficult to export your financial history if you ever decide to leave.
• Notes & Sources: As QuickBooks promotes, automated bank feeds are a core feature, but you’ll still be responsible for the review and categorization needed to keep your books accurate.

4) Xero​

A popular, modern alternative to QuickBooks, Xero offers similar capabilities with a focus on clean design and user experience.

• Good for: Business owners who prefer a more modern UI but need the same core capabilities as QuickBooks Online.
• Pros: Xero also has robust bank feeds and powerful reconciliation tools that make matching transactions straightforward. Its clean design is often praised by users, and a large number of accountants are fluent in the platform.
• Cons: The lower-priced tiers can have feature gaps (like limits on invoices or bills) that push you toward more expensive plans, and add-ons increase the total cost. And just like QBO, it faces the same "you still do the work" reality when it comes to the final categorization and review.
• Notes & Sources: According to Xero, its automated bank feeds connect to thousands of financial institutions worldwide to power its core reconciliation workflows.

5) Accountants (CPAs)​

Certified Public Accountants are highly trained financial experts who provide strategic advice, tax planning, and compliance services.

• Good for: Tax strategy, navigating complex financial situations, handling audits, and getting one-off advisory.
• Pros: A good CPA provides expert guidance on critical decisions like entity structure, tax optimization, and complex accounting treatments. Their oversight significantly reduces your risk on high-stakes financial matters.
• Cons: Hiring a CPA firm for day-to-day bookkeeping is prohibitively expensive for most small businesses. To be effective, they still need you to provide timely, organized financial records.
• What’s the difference from bookkeepers? In short, bookkeepers record and organize historical transactions, while accountants and CPAs interpret, report, and advise based on that data. (Investopedia, Intuit)

6) Traditional Bookkeepers​

A bookkeeper is a professional responsible for the weekly or monthly task of recording and reconciling your financial transactions.

• Good for: Business owners who want a dedicated person handling the weekly grind of bookkeeping.
• Pros: Human oversight greatly reduces common categorization errors that software alone can miss. At the end of each month, they produce a clean set of financial statements for you to review.
• Cons: This option is costlier than DIY software, with monthly retainers often starting in the hundreds of dollars. The turnaround time for reports and answers depends on your bookkeeper's availability and process.
• Reality Check: For many small businesses, the combination of a great bookkeeper for weekly tasks and periodic CPA support for tax and strategy is a durable and effective combo. (Pioneer Accounting Group)

7) Beancount.io (Plain-Text Accounting, Supercharged)​

This modern approach combines the control of spreadsheets with the automation of software and the precision of double-entry accounting.

• Good for: Developers, finance pros, and detail-oriented founders who demand precision, transparency, and automation without black boxes.
• What it is: Beancount.io is a platform built on the open-source Beancount methodology. Your entire financial ledger lives as human-readable plain text, which the platform transforms into real-time analysis, hosted Fava dashboards, and AI-assisted workflows.
• Why teams choose it:
  • Scriptable & Auditable: Version-control your books with Git. Every single change is reviewable in a diff, just like code.
  • Hosted Fava UI: Instantly generate income statements, balance sheets, and interactive charts directly from your text-based ledger. No manual report building.
  • AI Assistance: Speed up transaction categorization and anomaly detection while keeping humans in the loop for final approval.
  • True Portability: Your core data is a simple text file. You can export it anytime. There is zero vendor lock-in.
• Tradeoffs: There is a learning curve if you’ve never used double-entry accounting in a plain-text format. It's best suited for those who value absolute accuracy and control over the illusion of "push-button" convenience.

Prefer pure open source and self-hosting?​

You can always run the Beancount open-source engine on your own machine and use Fava as the web UI. It’s incredibly powerful and free, but you will be responsible for managing the setup, backups, and data integrations yourself. Beancount.io handles all of that for you.

Quick Comparison (At a Glance)​

How to Choose​

• Want maximum control, auditability, and developer-grade workflows? Choose Beancount.io. You get hosted Fava dashboards, AI assistance, and the freedom of plain-text portability.
• Want someone to “just handle it”? Hire a bookkeeper and keep a CPA on call for taxes and strategic questions.
• Comfortable in traditional SMB software ecosystems? QuickBooks or Xero are fine choices—just be sure to budget time each week to review and reconcile your transactions.
• Just testing the waters on a tight budget? Spreadsheets can work for a short time. Treat them as a stepping stone to a real system, not the final destination.

Why Plain-Text Accounting is Having a Moment​

Plain-text accounting (PTA) tools like Beancount are gaining traction because they emphasize reproducibility, version control, and transparency. These are values that resonate deeply with engineers, data scientists, and finance pros. If you believe your company's books should be as clear and reviewable as your code, you’re in the right place. (plaintextaccounting.org)

Ready to see your ledger come alive?​

Spin up a free Beancount.io workspace, import a small sample of last month’s transactions, and open the hosted Fava dashboard. You'll see your income statement and balance sheet appear instantly—then you can refine your categories with AI assistance.

Welcome to your developer-friendly guide to accounting concepts, tailored specifically for the world of plaintext accounting with Beancount. This dictionary bridges the gap between traditional finance terminology and Beancount's unique syntax, directives, and tools. Whether you're a seasoned developer new to accounting or a finance pro exploring plaintext methods, this A–Z reference will help you master your ledger.

How to Read Each Entry​

Each term is broken down into three parts for clarity:

• Conceptual Meaning — A simple, jargon-free explanation of the accounting or finance idea.
• Beancount Implementation — How the concept is represented or handled in Beancount, whether through directives, options, command-line tools, or reports.
• Example — A minimal, copy-paste-ready code snippet to illustrate the concept in a .beancount file.

Note: All examples adhere to the canonical syntax and behavior described in the official Beancount documentation.

A​

Account​

• Conceptual Meaning: A named category or "bucket" used to track the balance of something you own, owe, earn, or spend. Examples include your checking account, credit card, salary, or grocery expenses.
• Beancount Implementation: Account names are hierarchical and separated by colons (e.g., Assets:Bank:Checking). Every account must belong to one of the five root account types: Assets, Liabilities, Equity, Income, or Expenses.
• Example:

  2014-05-01 open Assets:US:BofA:Checking USD
  

Accounting Equation​

• Conceptual Meaning: The fundamental formula on which all accounting is based: Assets = Liabilities + Equity. It means that everything a business or individual owns (assets) is financed by either debt (liabilities) or the owner's own funds (equity).
• Beancount Implementation: This equation is automatically and rigorously enforced. Every transaction must be zero-sum, meaning the total of all its postings must equal zero. This design makes it impossible to create an unbalanced entry.

Accrual vs. Cash Basis​

• Conceptual Meaning: Two methods of recording transactions. Accrual basis records revenue when it's earned and expenses when they're incurred, regardless of when money changes hands. Cash basis records them only when cash is actually received or paid.
• Beancount Implementation: Beancount supports both methods. Accrual accounting is achieved by using Assets:Receivables for money owed to you and Liabilities:Payables for money you owe. Cash basis accounting simply omits these intermediate postings.

Amortization / Depreciation​

• Conceptual Meaning: The process of systematically spreading the cost of a tangible (depreciation) or intangible (amortization) asset over its useful life. For example, writing off the value of a company laptop over three years.
• Beancount Implementation: This is handled by creating periodic transactions that move a portion of the asset's cost from its asset account to an expense account (e.g., Expenses:Depreciation). This can be automated using scheduled transaction plugins.

B​

Balance Assertion​

• Conceptual Meaning: A checkpoint to confirm that your recorded balance for an account matches the real-world balance (e.g., from a bank statement) on a specific date. This is the core of reconciliation.
• Beancount Implementation: The balance directive asserts an account's total value at the start of the specified day. Beancount will raise an error if the calculated balance from all prior transactions does not match the asserted amount.
• Example:

  2024-01-31 balance Assets:US:BofA:Checking 154.20 USD
  

Balance Sheet​

• Conceptual Meaning: A financial statement that provides a snapshot of a company's or individual's financial health at a single point in time, showing assets, liabilities, and equity.
• Beancount Implementation: The web interface Fava provides an interactive Balance Sheet report. You can also generate one using Beancount's query language (bean-query or the newer standalone Beanquery tool).

Booking Method (Inventory Matching)​

• Conceptual Meaning: The method used to decide which previously purchased lots of an asset (like shares of a stock) are considered "sold" when a portion is divested. Common methods are FIFO (First-In, First-Out) and LIFO (Last-In, First-Out).
• Beancount Implementation: The booking method can be set globally with option "booking_method" ... or on a per-account basis in its open directive. Beancount's default is STRICT, which requires you to explicitly state which lot is being sold if there's any ambiguity. Other options include FIFO and LIFO.

Budget​

• Conceptual Meaning: A financial plan that estimates income and expenses over a specified period.
• Beancount Implementation: Budgeting is not a native feature of Beancount's core language. It is primarily implemented in the Fava web interface, which supports its own custom budget directives, or through community-developed plugins like fava-envelope.

C​

Capital Gain / Loss​

• Conceptual Meaning: The profit (capital gain) or loss (capital loss) resulting from the sale of a capital asset, such as stocks or real estate.
• Beancount Implementation: When you post a transaction that reduces a position (e.g., selling stock), Beancount automatically matches it against existing lots based on the booking method. You then post the calculated gain or loss to an appropriate income account, like Income:CapitalGains.

Chart of Accounts​

• Conceptual Meaning: A comprehensive, structured list of all accounts in the general ledger.
• Beancount Implementation: Your Chart of Accounts is implicitly defined by all the open directives and account names used throughout your ledger files. There is no separate file to define it.

Commodity / Currency​

• Conceptual Meaning: The unit of value being tracked. This can be a traditional currency (USD, EUR), a stock (AAPL), a loyalty point (AIRMILE), or any other quantifiable unit.
• Beancount Implementation: All such units are called "commodities." You can optionally declare them using the commodity directive to attach metadata, such as a full name or formatting rules.

Cost (Lot Cost)​

• Conceptual Meaning: The original price paid per unit for a specific purchase of an asset (a "lot"). This is crucial for calculating capital gains.
• Beancount Implementation: Lot cost is specified using curly braces {} on a posting. This information—cost, date, and an optional label—is attached to the lot and used for future matching.
• Example:

  2025-04-01 * "Buy Stock"
    Assets:Brokerage      25 HOOL {23.00 USD}
    Assets:Bank:Checking                -575.00 USD
  

Credit / Debit​

• Conceptual Meaning: The two sides of every accounting entry. In simple terms, a debit increases an asset or expense account, while a credit increases a liability, equity, or income account.
• Beancount Implementation: Beancount abstracts this away. You simply use positive and negative numbers. By convention, increases to Assets and Expenses are positive, while increases to Liabilities, Equity, and Income are represented by crediting them (which requires a negative number in your transaction). As long as the transaction sums to zero, the accounting is correct.

D​

Directive​

• Conceptual Meaning: A command or a declaration in the ledger that isn't a transaction but changes the state of the books (e.g., opening an account, recording a price).
• Beancount Implementation: Every line in a Beancount file is a directive. The main types include open, close, commodity, * (transaction), balance, pad, note, document, price, event, query, and custom.

Document​

• Conceptual Meaning: An external file, such as a PDF statement or a receipt image, linked to a transaction or account for record-keeping.
• Beancount Implementation: The document directive links a file to an account. If the option "documents" path is set, tools like Fava can automatically discover and associate files with transactions by their date and filename.
• Example:

  2024-02-01 document Assets:US:BofA:Checking "statements/2024-02-01.statement.pdf"
  

Double-Entry​

• Conceptual Meaning: The accounting principle that every transaction must affect at least two accounts and must balance (total debits must equal total credits).
• Beancount Implementation: This is the core, non-negotiable principle of Beancount. The zero-sum rule for all transaction postings ensures double-entry bookkeeping is always maintained.

E​

Equity​

• Conceptual Meaning: The net worth or owner's stake in the assets (Assets - Liabilities). This includes initial capital contributions and accumulated profits/losses (retained earnings).
• Beancount Implementation: Beancount uses Equity accounts for several internal functions, such as Equity:Opening-Balances to initialize account values and Equity:Earnings:Current to accumulate income and expense totals for reporting.

Event​

• Conceptual Meaning: A dated, non-financial marker on your timeline, useful for annotating life events like a job change, a move, or a vacation.
• Beancount Implementation: The event directive allows you to add a key-value pair to a specific date in your ledger.
• Example:

  2024-08-15 event "location" "Moved to San Francisco"
  

Exchange Rate​

• Conceptual Meaning: The value of one currency expressed in terms of another.
• Beancount Implementation: Exchange rates can be recorded with price directives for a specific date or specified directly within a transaction using inline prices (@ or @@).

F​

Fava​

• Conceptual Meaning: The modern, feature-rich web interface for Beancount.
• Beancount Implementation: Fava is a separate Python package you install and run against your Beancount file. It provides interactive charts, reports (Balance Sheet, Income Statement), budgeting tools, query execution, and a file editor, replacing most of the older bean-web and bean-report command-line tools.

FIFO / LIFO​

• Conceptual Meaning: Acronyms for "First-In, First-Out" and "Last-In, First-Out," which are two common booking methods for matching inventory sales.
• Beancount Implementation: These can be selected as the booking_method for an account or globally. (See Booking Method).

Flag​

• Conceptual Meaning: A status indicator on a transaction.
• Beancount Implementation: A transaction's flag appears after the date. * typically means "cleared" or "confirmed," while ! means "incomplete" or "needs review." Custom flags are also possible.

G​

General Ledger / Journal​

• Conceptual Meaning: A journal is a chronological record of all transactions. A ledger is a record of those same transactions, but sorted by account.
• Beancount Implementation: Your .beancount text files collectively form the journal. Tools like Fava or bean-query process this journal to generate ledgers (e.g., the transaction list for a single account) and other reports.

I​

Include​

• Conceptual Meaning: The practice of splitting a large ledger into multiple, more manageable files (e.g., by year or account type).
• Beancount Implementation: The include directive tells Beancount to parse the contents of another file as if it were part of the main file.
• Example:

  include "2024/transactions.beancount"
  include "accounts/open_accounts.beancount"
  

Inventory​

• Conceptual Meaning: The collection of all lots (units with a specific cost basis) held within an account at any given time.
• Beancount Implementation: This is a core Beancount concept. Each account that holds non-currency commodities maintains an inventory of lots. When you sell or transfer units, Beancount reduces the inventory according to the booking method.

Inline Price vs. Total Price​

• Conceptual Meaning: Two ways to specify the conversion price within a transaction posting. You can either price it per unit or define the total price for the entire posting.
• Beancount Implementation:
  • @ sets a per-unit price.
  • @@ sets a total price for the line.
• Example (per-unit):

  2025-01-05 * "FX Transfer"
    Assets:USD    -100.00 USD @ 1.34 CAD
    Assets:CAD
  

L​

Link​

• Conceptual Meaning: A unique identifier used to connect multiple, separate transactions that are part of a single logical event (e.g., a credit card payment and the corresponding bank withdrawal).
• Beancount Implementation: Add a ^link_id to each transaction you want to group. Fava and other tools can then display these linked transactions together.
• Example: ^cc-payment-2025-01

Lot​

• Conceptual Meaning: A specific quantity of a commodity purchased at a particular date and cost.
• Beancount Implementation: A lot is defined by its amount, commodity, cost, date, and an optional label. Lots are created using the {...} cost basis syntax and are tracked in an account's inventory.

M​

Metadata​

• Conceptual Meaning: Additional key-value data attached to a transaction or posting for extra context, filtering, or analysis.
• Beancount Implementation: Metadata is added on the same line as a transaction or posting. Keys are lowercase, followed by a colon and a string, number, or other value.
• Example:

  2025-03-02 * "Dinner"
    Expenses:Food  23.91 CAD  ; receipt: "2025-03-02-1234.pdf", city: "Montreal"
    Assets:Cash   -23.91 CAD
  

Multi-Currency​

• Conceptual Meaning: The ability to handle and report on transactions involving multiple different currencies or commodities simultaneously.
• Beancount Implementation: This is a native, first-class feature. Beancount tracks each commodity independently within each account. The operating_currency option is used to specify which currencies reports should be converted to for display.

N​

Narration / Payee​

• Conceptual Meaning: The descriptive text for a transaction. The payee is who you paid or who paid you, and the narration is a description of what the transaction was for.
• Beancount Implementation: These are the two optional quoted strings that follow the transaction flag. The first is typically the payee, the second is the narration.
• Example: 2025-03-19 * "Acme Corp" "Salary"

Note​

• Conceptual Meaning: A dated comment associated with a specific account, separate from any transaction.
• Beancount Implementation: The note directive adds a text comment to an account's ledger on a given date.
• Example:

  2014-04-10 note Assets:US:BofA:Checking "Called support to dispute a charge."
  

O​

Open / Close​

• Conceptual Meaning: The actions of starting to use a new account or formally stopping the use of an existing one.
• Beancount Implementation: The open directive is required before an account can be used in a transaction. The close directive marks it as inactive after a certain date.
• Example:

  2016-11-28 close Liabilities:CreditCard:CapitalOne
  

Operating Currency​

• Conceptual Meaning: The primary currency (or currencies) that you want to see your financial reports in.
• Beancount Implementation: Set via option "operating_currency" "USD". This tells tools like Fava to display columns converted to this currency using the price data available in your ledger.

P​

Pad​

• Conceptual Meaning: A directive that automatically inserts a transaction to bring an account to a desired balance, booking the difference to another specified account.
• Beancount Implementation: pad is often used to initialize an account's starting balance against Equity:Opening-Balances. It creates a transaction behind the scenes.
• Example:

  2025-01-31 pad Assets:Cash Equity:Opening-Balances
  

Posting​

• Conceptual Meaning: A single entry within a transaction that debits or credits an account. Every transaction is composed of at least two postings.
• Beancount Implementation: Each line under a transaction that specifies an account and an amount is a posting. The sum of all postings in a transaction must be zero.

Price​

• Conceptual Meaning: A record of the market value or exchange rate of one commodity in terms of another on a specific date.
• Beancount Implementation: The price directive creates a historical database of rates that Beancount uses for valuation in reports. The bean-price tool can help fetch and update these prices from online sources.
• Example:

  2025-02-03 price EUR 1.10 USD
  

Plugin​

• Conceptual Meaning: A piece of custom code that can modify or analyze your ledger data as it's being loaded.
• Beancount Implementation: Plugins are loaded using the plugin "module.name" "config" directive. They can be used for anything from automatically adding tags to implementing complex scheduled transactions.

Q​

Query Language (BQL / Beanquery)​

• Conceptual Meaning: An SQL-like language for performing sophisticated queries and generating custom reports from your ledger data.
• Beancount Implementation: Beancount has a powerful query language. You can use it via the command-line tool bean-query or interactively in Fava's "Query" page. A newer, standalone version called Beanquery is the future of this tool.
• Example:

  SELECT account, sum(position)
  WHERE account ~ "^Expenses"
  GROUP BY account
  ORDER BY sum(position)
  

R​

Reconciliation​

• Conceptual Meaning: The process of comparing your internal financial records against external statements (from a bank, credit card company, etc.) to ensure they match and to identify any discrepancies.
• Beancount Implementation: Reconciliation is primarily done using balance assertions. You can also use document directives to link to the statements you are reconciling against.

Realized vs. Unrealized Gains​

• Conceptual Meaning: A realized gain is a profit from a sale that has been completed. An unrealized gain is a "paper" profit on an asset you still own, based on its current market value.
• Beancount Implementation: Realized gains are explicitly recorded when you sell an asset. Unrealized gains are not recorded in the ledger itself but can be calculated and displayed in reports by Fava and other tools, which value your holdings using your price database.

Rounding / Tolerance​

• Conceptual Meaning: A small margin of error allowed when comparing numbers to account for rounding differences, especially in multi-currency transactions.
• Beancount Implementation: Beancount has rules for inferring precision from your entries and allows setting a tolerance for balancing checks. This prevents errors from trivial discrepancies like $0.001$.

S​

Statements​

• Conceptual Meaning: Official records from financial institutions (banks, brokers) listing all transactions for a given period.
• Beancount Implementation: These are typically imported into Beancount format using importer scripts (part of the beancount.ingest library). Once imported, the original statement file (e.g., a PDF) can be linked with a document directive.

Subaccount​

• Conceptual Meaning: A child account nested under a parent account to create a more detailed hierarchy.
• Beancount Implementation: The colon : syntax creates subaccounts. For example, Expenses:Food:Restaurants is a subaccount of Expenses:Food.

T​

Tag​

• Conceptual Meaning: A simple, flexible label used to categorize or filter transactions, often for events that cross multiple expense categories (like a vacation or a work trip).
• Beancount Implementation: Tags are denoted with a # (e.g., #vacation-2025). A tag on a transaction line applies to all postings below it.
• Example:

  2025-01-10 * "Conference Hotel" #work #travel-sfo-2025
    Expenses:Travel:Hotel   620.00 USD
    Assets:Bank:Checking   -620.00 USD
  

Transaction​

• Conceptual Meaning: A dated financial event that moves value between two or more accounts.
• Beancount Implementation: The fundamental data entry in Beancount. It starts with a date and a flag (* or !), is followed by an optional payee and narration, and contains two or more indented posting lines.
• Example:

  2025-03-19 * "Acme Corp" "Salary"
    Assets:Bank:Checking      3062.68 USD
    Income:Salary            -3062.68 USD
  

Trial Balance​

• Conceptual Meaning: A report that lists all accounts and their balances. The totals of the debit and credit columns should be equal, confirming the ledger is in balance.
• Beancount Implementation: Because Beancount enforces the zero-sum rule on every transaction, the ledger is always in balance. A trial balance can be generated via a query, but it's not a necessary check as it is in manual accounting.

U–Z​

Valuation​

• Conceptual Meaning: The process of expressing the value of all your holdings in a single, common currency (an operating currency).
• Beancount Implementation: Tools like Fava perform valuation at report time. They use the price directives in your ledger to convert the value of all commodities (stocks, foreign currencies) into your chosen operating_currency.

Year-End Close​

• Conceptual Meaning: In traditional accounting, this is a formal process where the balances of all temporary income and expense accounts are moved to an equity account (like Retained Earnings) to start the new year fresh.
• Beancount Implementation: Beancount ledgers are append-only; you never modify past entries. "Closing the books" is a reporting concept. Fava and query tools can show you an income statement for a specific period (e.g., a year) and carry forward the net result, but the raw ledger file remains a continuous, unbroken history.

Zero-Sum​

• Conceptual Meaning: The principle that the sum of all debits and credits in a transaction must equal zero.
• Beancount Implementation: This is a core invariant. The bean-check tool will report an error if any transaction's postings do not sum to zero (within a given tolerance).

Beancount CLI & Tooling Quick-Map ⚙️​

• bean-check: Validates your ledger's syntax, balances, and core accounting rules. Run this first!
• bean-format: Automatically formats your file, aligning numbers and currencies for readability.
• bean-price: Fetches market prices for stocks and currencies and formats them as price directives.
• bean-query: The command-line interface for running BQL/Beanquery queries.
• bean-report: (Largely deprecated) A v2 tool for generating command-line reports. Modern workflows should use Fava or bean-query instead.

Five Essential Snippets for Daily Use​

1. Everyday Expense

   2025-04-10 * "Cafe Mogador" "Lunch"
     Expenses:Food:Restaurants    17.45 USD
     Assets:Bank:Checking        -17.45 USD
   

2. Balance Assertion (for Reconciliation)

   2025-04-30 balance Assets:Bank:Checking  2345.67 USD
   

3. Investment Purchase with Cost Basis

   2025-05-02 * "Vanguard" "Buy ETF"
     Assets:Brokerage:Vanguard      100 VEA {50.00 USD}
     Assets:Bank:Checking            -5000.00 USD
   

4. FX Transfer with Inline Price

   2025-06-01 * "Wise" "Convert USD to CAD"
     Assets:USD    -100.00 USD @ 1.36 CAD
     Assets:CAD
   

5. Daily Market Price Update

   2025-06-01 price VEA  53.12 USD
   

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!

If you run a business that bills clients, you need a rock-solid way to track who owes you money. This is where Accounts Receivable (AR) comes in. It’s more than just a number on a report; it’s the lifeblood of your cash flow.

This guide will walk you through what Accounts Receivable is, why it matters, and how to manage it with precision and clarity using the plain-text accounting system, Beancount.

TL;DR​

Accounts receivable (AR) is the money customers owe you for goods or services you’ve already delivered. It’s a current asset on your balance sheet, central to accrual accounting, and a key driver of your business's cash flow. You can track AR cleanly in Beancount by using customer sub-accounts, linking invoices to payments with ^links, and running a few simple queries. To measure your collection speed, you can calculate AR Turnover and Days Sales Outstanding (DSO). To handle risk, you can use an allowance for doubtful accounts.

What is Accounts Receivable?​

Definition Accounts Receivable represents the balance of money due to your firm for goods or services delivered or used but not yet paid for by customers. Under accrual accounting, you recognize this revenue when you earn it, not when you receive the cash. As a result, AR appears as a current asset on your company's balance sheet.

Why It Matters Effectively managing your AR is critical for maintaining healthy liquidity. The faster you collect on your invoices, the shorter your cash conversion cycle—the time it takes to turn your investments in inventory and other resources back into cash. By monitoring metrics like AR Turnover and Days Sales Outstanding (DSO), you can get a clear picture of your collection efficiency and take action to improve it.

Accounts Receivable vs. Accounts Payable (One-Line Refresher)

• AR = money owed to you (it's an asset).
• AP = money you owe to others (it's a liability).

The Accounts Receivable Flow in Double-Entry Accounting​

Conceptually, the lifecycle of a receivable follows these steps:

1. Issuing an Invoice (Credit Sale): When you send an invoice, you increase your Assets (specifically, Accounts Receivable) and recognize the Income you've earned.
2. Cash Collection: When the customer pays, you increase one asset (your Assets:Bank account) and decrease another (Assets:AR). The net effect on your total assets is zero, but your cash position improves.
3. Discounts or Credits: If you offer an early-payment discount or issue a credit memo, you reduce the customer's AR balance and offset it with a discount expense or a reduction in revenue (contra-revenue).
4. Bad Debts: Unfortunately, not all invoices get paid. To account for this, you can recognize an allowance for doubtful accounts (a contra-asset that reduces your AR's value) and a corresponding bad debt expense. Later, you can write off a specific uncollectible invoice against this allowance.

Modeling AR in Beancount​

Beancount is a plain-text, double-entry accounting system that is perfectly suited for tracking AR. Its use of tags (which start with #), links (which start with ^), and a SQL-like query language (bean-query) makes your entire AR process transparent, auditable, and scriptable.

Suggested Account Structure​

A clean chart of accounts is the foundation. Here’s a recommended structure:

Assets:AR
Assets:AR:Clients:<Name>
Assets:AR:Allowance            ; A contra-asset account

Income:Sales
Income:Contra:SalesDiscounts   ; An alternative to an expense account

Expenses:SalesDiscounts
Expenses:BadDebt

1. Record a Credit Sale (Issue an Invoice)​

When you send an invoice to a client, you record it in your ledger.

2025-07-01 * "Acme Co." "Invoice 2025-045 · Web design" ^INV-2025-045 #ar #client:acme
  invoice: "2025-045"
  due: "2025-07-31"
  document: "/invoices/2025/INV-2025-045.pdf"
  Assets:AR:Clients:Acme-Co           1200.00 USD
  Income:Sales                       -1200.00 USD

• The ^INV-2025-045 link is a unique identifier that will tie this invoice to its future payment(s).
• The document: metadata helps Fava (Beancount's web interface) render a clickable link directly to the invoice PDF.

2. Record Full Payment​

When Acme Co. pays the invoice in full, you clear their receivable balance.

2025-07-25 * "Acme Co." "Payment for INV-2025-045" ^INV-2025-045 #ar
  Assets:Bank:Checking                1200.00 USD
  Assets:AR:Clients:Acme-Co          -1200.00 USD

Using the same ^INV-2025-045 link creates a clear audit trail connecting the invoice and the payment.

3. Handling Partial Payments​

If a client makes a partial payment, the process is the same. The link keeps everything connected.

2025-07-20 * "Acme Co." "Partial payment INV-2025-045" ^INV-2025-045 #ar
  Assets:Bank:Checking                 400.00 USD
  Assets:AR:Clients:Acme-Co           -400.00 USD

A query on ^INV-2025-045 would show the original $1200 invoice and this$400 payment, leaving an $800 balance.

4. Handling an Early-Payment Discount​

Let's say you offer a 2% discount on a $1000 invoice if paid early.

2025-07-10 * "Acme Co." "2% early-payment discount on INV-2025-046" ^INV-2025-046 #ar
  Assets:Bank:Checking                 980.00 USD
  Expenses:SalesDiscounts               20.00 USD
  Assets:AR:Clients:Acme-Co          -1000.00 USD

Here, you clear the full $1000 receivable, record the$980 cash received, and book the $20 discount as an expense. Note: Many ledgers treat sales discounts as contra-revenue instead of an expense. Using an expense account is often simpler for smaller ledgers. The key is to choose one method and use it consistently.

5. Including Sales Tax on Invoices​

If you collect sales tax, you record it as a liability at the time of invoicing.

2025-07-01 * "Acme Co." "INV-2025-047 · Hardware + tax" ^INV-2025-047 #ar
  invoice: "2025-047"
  due: "2025-07-31"
  Assets:AR:Clients:Acme-Co           1100.00 USD
  Income:Sales                       -1000.00 USD
  Liabilities:Tax:Sales               -100.00 USD

You've invoiced for $1100, recognized$1000 in revenue, and now owe $100 to the tax authority.

6. Handling Bad Debts (Allowance Method)​

The allowance method is preferred under Generally Accepted Accounting Principles (GAAP) as it better matches expenses to revenues.

Step 1: Estimate and Create the Allowance (e.g., at Year-End) Based on historical data, you estimate a percentage of your receivables may be uncollectible.

2025-12-31 * "Allowance for doubtful accounts (2% of AR)"
  Expenses:BadDebt                     300.00 USD
  Assets:AR:Allowance                 -300.00 USD

This creates a contra-asset account (Assets:AR:Allowance) that reduces the book value of your total receivables.

Step 2: Write Off a Specific Uncollectible Invoice Later When you are certain an invoice will not be paid, you write it off against the allowance.

2026-03-05 * "Write-off INV-2025-049 for Insolvent Client" ^INV-2025-049 #ar
  Assets:AR:Allowance                 1200.00 USD
  Assets:AR:Clients:Insolvent-Client -1200.00 USD

Notice this transaction does not impact your expenses; the expense was already recognized when you created the allowance.

Minimal Reporting & Queries​

You can get quick snapshots of your AR using Fava or bean-query.

Open Receivables by Customer

SELECT account, SUM(position)
WHERE account ~ '^Assets:AR'
GROUP BY account
ORDER BY account;

Journal of AR Activity for a Period

JOURNAL
WHERE account ~ '^Assets:AR'
  AND date >= 2025-07-01 AND date < 2025-08-01;

Core AR Metrics (With Quick Formulas)​

For these ratios, a practical approach is to use bean-query to export the necessary numbers (period sales, beginning/ending AR balances) and then perform the calculations in a spreadsheet or a script. This keeps your ledger clean and your math explicit.

AR Turnover Ratio​

This measures how many times per period your business collects its average accounts receivable. Higher is better.

$AR\\ Turnover = \\frac{Net\\ Credit\\ Sales}{Average\\ AR}$

DSO (Days Sales Outstanding)​

This tells you the average number of days it takes to collect payment after a sale has been made. Lower is better.

$DSO = (\\frac{Accounts\\ Receivable}{Total\\ Credit\\ Sales}) \\times Number\\ of\\ Days$

Together, these metrics indicate how efficiently you convert invoices into cash.

A Simple Beancount Starter File (Copy/Paste)​

; --- Accounts ---------------------------------------------------------------
1970-01-01 open Assets:Bank:Checking           USD
1970-01-01 open Assets:AR
1970-01-01 open Assets:AR:Clients:Acme-Co
1970-01-01 open Assets:AR:Allowance
1970-01-01 open Income:Sales
1970-01-01 open Expenses:SalesDiscounts
1970-01-01 open Expenses:BadDebt
1970-01-01 open Liabilities:Tax:Sales          USD
; ---------------------------------------------------------------------------

; Example invoice
2025-07-01 * "Acme Co." "Invoice 2025-045 · Web design" ^INV-2025-045 #ar
  invoice: "2025-045"
  due: "2025-07-31"
  document: "/invoices/2025/INV-2025-045.pdf"
  Assets:AR:Clients:Acme-Co           1200.00 USD
  Income:Sales                       -1200.00 USD

; Payment received
2025-07-25 * "Acme Co." "Payment INV-2025-045" ^INV-2025-045 #ar
  Assets:Bank:Checking                1200.00 USD
  Assets:AR:Clients:Acme-Co          -1200.00 USD

Operational Tips to Keep AR Healthy​

• Set Clear Terms: Include the due date, late fee policies, and any early-payment discount terms on every invoice.
• Link Everything: Use consistent ^INV-... links to tie invoices, payments, and credit memos together for a clear audit trail.
• Attach Documents: Use the document: metadata to link to PDFs of invoices, purchase orders, and contracts.
• Review Monthly: Check your open AR report at least once a month and follow up on past-due invoices. Watch your AR Turnover and DSO trends to spot problems early.

Further Reading (Sources Used)​

• Investopedia on AR basics and DSO
• Beancount documentation for syntax, links/tags, and the query language
• Lumen Learning on the allowance vs. direct write-off methods