Accounting Dictionary for Beancount Users (A–Z)

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