35 posts tagged with "financial management"

In today's blog post, we will be breaking down a Beancount ledger for businesses, which will help you understand the intricacies of this plain text double-entry accounting system.

Let's start with the code first:

1970-01-01 open Assets:Bank:Mercury
1970-01-01 open Assets:Crypto

1970-01-01 open Equity:Bank:Chase

1970-01-01 open Income:Stripe
1970-01-01 open Income:Crypto:ETH

1970-01-01 open Expenses:COGS
1970-01-01 open Expenses:COGS:Contabo
1970-01-01 open Expenses:COGS:AmazonWebServices

1970-01-01 open Expenses:BusinessExpenses
1970-01-01 open Expenses:BusinessExpenses:ChatGPT

2023-05-14 * "CONTABO.COM" "Mercury Checking ••1234"
  Expenses:COGS:Contabo                               17.49 USD
  Assets:Bank:Mercury                                -17.49 USD

2023-05-11 * "Amazon Web Services" "Mercury Checking ••1234"
  Expenses:COGS:AmazonWebServices                  14490.33 USD
  Assets:Bank:Mercury                             -14490.33 USD

2023-03-01 * "STRIPE" "Mercury Checking ••1234"
  Income:Stripe                                   -21230.75 USD
  Assets:Bank:Mercury                              21230.75 USD

2023-05-18 * "customer_182734" "0x5190E84918FD67706A9DFDb337d5744dF4EE5f3f"
  Assets:Crypto                                         -19 ETH {1,856.20 USD}
  Income:Crypto:ETH                                      19 ETH @@ 35267.8 USD

Understanding the Code​

1. Opening Accounts: The code starts by opening a series of accounts on 1970-01-01. These include a mix of asset accounts (Assets:Bank:Mercury and Assets:Crypto), an equity account (Equity:Bank:Chase), income accounts (Income:Stripe and Income:Crypto:ETH), and expense accounts (Expenses:COGS, Expenses:COGS:AmazonWebServices, Expenses:BusinessExpenses, and Expenses:BusinessExpenses:ChatGPT).

2. Transactions: It then progresses to record a series of transactions between 2023-03-01 and 2023-05-18.

   • The transaction on 2023-05-14 represents a payment of $17.49 to CONTABO.COM from Mercury Checking ••1234. This is recorded as an expense (Expenses:COGS:Contabo) and a corresponding deduction from the Assets:Bank:Mercury account.

   • Similarly, the transaction on 2023-05-11 represents a payment of $14490.33 to Amazon Web Services from the same bank account. This is logged under Expenses:COGS:AmazonWebServices.

   • The transaction on 2023-03-01 shows income from STRIPE being deposited into Mercury Checking ••1234, totaling $21230.75. This is recorded as income (Income:Stripe) and an addition to the bank account (Assets:Bank:Mercury).

   • The last transaction on 2023-05-18 represents a crypto transaction involving 19 ETH from a customer. This is tracked under Assets:Crypto and Income:Crypto:ETH. The {1,856.20 USD} shows the price of ETH at the time of transaction, while the @@ 35267.8 USD specifies the total value of the 19 ETH transaction.

In all transactions, the principle of double-entry accounting is maintained, ensuring that the equation Assets = Liabilities + Equity always holds true.

Final Thoughts​

This Beancount ledger provides a straightforward yet robust system for tracking financial transactions. As seen in the final transaction, Beancount is flexible enough to account for non-traditional assets like cryptocurrency, which is a testament to its utility in our increasingly digital financial landscape.

We hope this breakdown helps you better understand the structure and capabilities of Beancount, whether you're a seasoned accountant or a beginner trying to keep track of your personal finances. Stay tuned for our next blog post, where we'll delve further into advanced Beancount operations.

A plain‑text template, a repeatable workflow, and a single query for “Who still owes me?”

Invoicing can feel like a chore, stuck between the work you've finished and the payment you're waiting for. But a good invoice process is the backbone of healthy cash flow. It pulls double duty: it clearly tells your clients what they owe and when, and it feeds your accounting system the unassailable facts it needs.

While dedicated SaaS apps can send slick, automated PDFs, they often come with monthly fees and lock your data in a proprietary silo. A lightweight, plain-text approach using Beancount offers a powerful alternative. You can turn each invoice into a clear set of accounting entries, giving you all the benefits of version control, powerful metadata, and instant querying—no subscription required.

The Minimum Viable Invoice (Fields You Should Never Skip)​

Before you touch your ledger, you need a professional invoice. The format can be simple, but the contents must be precise. These fields, borrowed from time-tested small-business practice, are non-negotiable.

• Seller details: Your business name and physical address.
• Client details: Your client’s name and (ideally) their address.
• Invoice number: A unique, sequential ID that is never reused. INV-045 follows INV-044.
• Issue & due dates: Clearly state when the invoice was issued and when payment is expected.
• Line items: A clear description of services or products, along with quantity, rate, and the line total.
• Subtotal, tax, and total: Show the math so the client can follow it easily.
• Optional notes: A place for a thank you, wiring instructions, or a client-provided purchase order number.

To get you started, we've created a set of ready-to-edit templates that include all these fields. The spreadsheet versions even pre-calculate the totals for you.

Note: Invoice templates are coming soon! In the meantime, you can create your own using the fields listed above in Google Docs, Word, Sheets, Excel, or any other document format.

Record the Invoice in Your Ledger​

Once you've sent the invoice PDF to your client, you must record it in Beancount. This is a crucial step that recognizes the revenue when it's earned, not just when it's paid. The process involves two distinct transactions.

1. When you issue the invoice:

You create a transaction that moves the total amount from your Income account into Assets:AccountsReceivable. This creates a digital IOU in your books.

; 2025‑07‑21 Invoice #045  Web design sprint for Acme Corp.
2025-07-21 * "Acme Corp" "INV-045 Web design sprint"
  Assets:AccountsReceivable          3500.00 USD  ; due:2025-08-04
  Income:Design:Web
  invoice_id: "INV-045"
  contact_email: "[email protected]"
  link: "docs/invoices/2025-07-21_Acme_INV-045.pdf"

Here, you debit AccountsReceivable and credit your Income account. Notice the rich metadata: the due date, a unique invoice_id, and even a direct link: to the PDF you sent.

2. When the client pays:

When the cash hits your bank account, you record a second transaction to "close out" the IOU. This moves the balance from AccountsReceivable to your checking account.

2025-08-01 * "Acme Corp" "Payment INV-045"
  Assets:Bank:Checking               3500.00 USD
  Assets:AccountsReceivable
  invoice_id: "INV-045"

The balance for INV-045 in Assets:AccountsReceivable is now zero, and your books are perfectly balanced.

Attach the PDF: The link: metadata key is especially powerful when used with Fava, Beancount's web interface. Fava will render a clickable link directly in the transaction view, so the source document is never more than a click away. This workflow was envisioned as early as 2016 in a feature request (GitHub).

One Query to List All Open Invoices​

So, who still owes you money? With this system, you don't need to hunt through emails or spreadsheets. You just need one simple query.

Save the following as a file named open-invoices.sql:

SELECT
  meta('invoice_id') AS id,
  payee,
  narration,
  date,
  number(balance) AS outstanding
WHERE
  account = "Assets:AccountsReceivable"
  AND balance != 0
ORDER BY
  date;

Now, run it from your command line:

bean-query books.beancount open-invoices.sql

In seconds, you'll get a clean, up-to-the-minute aging report of all outstanding invoices, showing the invoice ID, client, date issued, and amount owed. No extra software required.

Automate the Busywork​

The beauty of plain text is scriptability. You can automate the tedious parts of this workflow.

• Template + Pandoc = PDF: Maintain your invoice template in Markdown. A tiny Python script can populate the variables (client name, line items, invoice number), and the command-line tool Pandoc can instantly convert it to a professional PDF.
• Git Pre-commit Hook: If you store your ledger in Git, a simple pre-commit hook can run checks before you save your work. It can verify that every new invoice_id is unique, that the transaction postings balance to zero, and that the file referenced in the link: metadata actually exists.
• Cron Job: Set up a scheduled task (a cron job) to run your open-invoices.sql query every night and email you the summary. You'll start each day knowing exactly who needs a friendly nudge.

A Realistic Caveat​

Beancount is an accounting tool, not an invoicing service. It will not automatically send payment reminders to your clients or process their credit card payments. The workflow is: you create and send the invoice using your chosen method (like the templates above), and then you book the accounting entries in your ledger.

For most freelancers and small shops, this manual step is a small price to pay for a bulletproof, auditable, and free accounting system that you completely own and control (beancount.io).

Next Steps​

Ready to take control of your invoicing? Here’s how to start.

1. Download a template and use it to create your next real invoice, making sure to use a sequential invoice number.
2. Store your sent PDFs in a dedicated folder like docs/invoices/ and use the link: metadata key in your Beancount transaction to reference them.
3. Save the open-invoices.sql query and make running it a part of your weekly financial review.

Plain-text accounting doesn’t mean giving up polish or control—it just means the database is grep-able. With a simple template and the snippets above, you’ll get paid faster and keep your books immaculate.

Many of our customers have been asking us how to add multiple files to one ledger since February. They need the file structure to archive or categorize transactions. So, finally, after a couple of months of work, we are glad to announce the feature is released for free.

Here is how to use it:

File > create a new file​

Go to the file editor tab on the left navigation sidebar. And then, follow the "File" dropdown and click "Create a new file".

Name your new file​

Give your file a valid filename and save it. All filenames must be ended with ".bean".

Include the file​

Here is a crucial step, you have to include the newly-created file in main.bean.

For example, if you added stock.bean, then specify include "stock.bean" in main.bean.

Refresh and navigate to file​

Refresh the page, and you will see the file appears in the "File" dropdown.

Rename or delete the file​

When navigated to the file, you could rename or delete it in the "Edit" dropdown.

Having troubles?​

Ask questions in https://t.me/beancount.

We're excited to announce a major milestone in Beancount's evolution: the launch of our dedicated mobile apps for both iOS and Android platforms! This release directly addresses one of the most frequent requests from our community – the ability to manage your ledger efficiently on mobile devices.

Key Features​

• Quick Transaction Entry: Seamlessly add new transactions on the go
• Mobile Financial Reports: Access your financial insights anywhere, anytime
• Direct Ledger Editing: Full access to your ledger file through an optimized web view
• Cross-Platform Sync: Keep your financial data consistent across all your devices

Community-Driven Development​

This release marks just the beginning of our mobile journey. We're committed to evolving these apps based on your needs and feedback. Join our vibrant community on Telegram at https://t.me/beancount to discuss Beancount, share your experience, and help shape future features.

Our Vision​

At Beancount, our mission is to empower everyone to achieve better financial control and understanding. These mobile apps represent a significant step toward that goal, with many more exciting features and tools on our roadmap.

You can’t steer a business if you don’t know where the money goes. Accurate books turn guesswork into insight. (Investopedia)

Every business owner, freelancer, or startup founder eventually faces the same reality: financial chaos is a growth killer. Without a clear picture of your cash flow, you're flying blind. But what if you could manage your finances with the same precision and control you apply to your code? Enter Beancount, a powerful, open-source accounting system that runs on plain-text files.

This guide will walk you through the fundamentals of bookkeeping and show you how to build a robust, lightweight, and transparent financial workflow using Beancount.

What Is Bookkeeping?​

At its core, bookkeeping is the systematic and continuous recording of every financial transaction a business makes. It’s the daily discipline of tracking revenue, expenses, assets (what you own), and liabilities (what you owe).

In the world of Beancount, these records aren't locked away in proprietary software. They live in simple, human-readable plain-text files. This approach allows you to version-control your financial history with tools like Git, just as you would with a software project. Every entry is governed by the double-entry balancing rule, an elegant system that automatically checks your work and ensures your books are always correct. (beancount)

Why It Matters​

Meticulous bookkeeping isn't just about administrative tidiness; it's a strategic advantage.

• Tax confidence: When tax season rolls around, clean records are your best friend. The IRS requires clear documentation for income and deductions. A well-maintained ledger means you can file with confidence and dramatically shorten any potential audits. (IRS)
• Sharper decisions: Are your prices high enough? Is a specific service contract actually profitable? Are subscription costs spiraling out of control? Financial statements like the income statement and balance sheet reveal pricing leaks, runaway costs, and cash-flow potholes, giving managers and investors the data they need to make smart choices. (Investopedia)
• Easier funding: Lenders and investors don't make decisions based on gut feelings. Before wiring funds, they will ask for financial statements. Good books allow you to generate a balance sheet or income statement in seconds, demonstrating professionalism and financial health. (Investopedia)
• Fraud and error alerts: Routine reconciliation of your books against bank statements is your first line of defense against mistakes. This simple habit helps you catch duplicate charges, bank errors, or fraudulent activity quickly, before they become significant problems. (IRS)

A Seven-Step Plain-Text Blueprint​

Ready to get started? Here’s how to build your Beancount-powered bookkeeping system from the ground up.

1. Separate Business and Personal Accounts​

This is the non-negotiable first step. Open a dedicated business checking account and, if needed, a business credit card. Commingling funds creates a nightmare for accounting and can blur the liability lines between you and your business. Clean separation is essential for accurate deductions and legal protection. (Small Business Administration)

In Beancount, you declare the existence of these accounts with an open directive:

; Opening balances for your accounts
2025-07-22 open Assets:Bank:Business   USD
2025-07-22 open Assets:Bank:Personal   USD

2. Pick a Bookkeeping System​

Beancount uses the double-entry method, the gold standard of accounting for centuries. The principle is simple: every transaction affects at least two accounts. For every debit from one account, there must be a corresponding credit to another. The magic of this system is that the sum of all your accounts must always balance to zero. Beancount enforces this rule automatically, meaning a typo or logical error will immediately raise a flag. You literally can't have unbalanced books. (beancount)

3. Decide on an Accounting Method​

You have two main choices here:

• Cash basis: You record income when you receive the money and expenses when you pay them. It’s simpler and reflects your cash flow directly.
• Accrual basis: You record income when you earn it (e.g., when an invoice is sent) and expenses when you incur them (e.g., when you receive a bill). This method gives a truer picture of a company's financial health and performance, especially for growing firms. (Investopedia)

Here is an example of an accrual transaction in Beancount. You book the income when the invoice is sent, moving the value into Assets:AccountsReceivable. When the client pays, you move the cash from AccountsReceivable to your bank account.

; Accrual example: invoice issued, payment later
2025-07-22 * "Design invoice #101"
  Assets:AccountsReceivable     3000.00 USD
  Income:Design

2025-08-15 * "Client pays invoice #101"
  Assets:Bank:Business          3000.00 USD
  Assets:AccountsReceivable

4. Assemble Your Tool Stack​

The beauty of Beancount is its minimalist, modular nature. Your core stack includes:

• Editor + Git: Your favorite text editor for journaling transactions and Git for version control, giving you a complete, auditable history of every change.
• bean-report / bean-balance / Fava: Command-line tools like bean-report and the stunning web interface Fava give you instant financial statements, dashboards, and powerful filtering capabilities.
• Importers: A rich ecosystem of community-built importers can connect to your bank feeds via CSV, Plaid, or APIs for services like Stripe and PayPal, automating much of the data entry.

5. Categorize Every Transaction​

A well-organized "chart of accounts" is the backbone of insightful reporting. Define categories that make sense for your business, using hierarchical accounts for granularity. Then, as you record transactions, categorize them meticulously.

2025-07-30 * "AWS monthly bill"
  Expenses:Hosting:AWS       124.50 USD
  Assets:Bank:Business
  tag: "ops"

In this example, the expense is clearly filed under Expenses:Hosting:AWS. The use of tag: "ops" also allows for cross-cutting reports, like viewing all operational expenses regardless of their primary category. (IRS)

6. Store Source Documents Securely​

The IRS happily accepts digital copies of receipts and invoices. Scan paper receipts or forward email invoices to a dedicated folder in cloud storage (like Google Drive or Dropbox). Then, link to the file directly in your Beancount entry using metadata. This creates an airtight, self-contained record.

; Receipt image linked as metadata
2025-07-18 * "Team lunch"
  Expenses:Meals              85.10 USD
  Assets:Bank:Business
  receipt: "receipts/2025-07-18-team-lunch.jpg"

7. Make Bookkeeping a Habit​

Consistency is key. Procrastination turns bookkeeping into a stressful, time-consuming chore. Set aside a recurring time block—a weekly or monthly “Bean-day”—to import transactions, reconcile accounts, and review your financial reports. This simple routine transforms bookkeeping from a quarterly scramble into a quick, empowering business health check. (IRS)

DIY vs Professional Help​

• DIY: For freelancers or small businesses with predictable transaction volume, a DIY approach with Beancount is incredibly effective. It's still wise to have a brief, one-time consultation with a CPA to validate your chart of accounts and ensure you're on the right track.
• Professional review: As your business scales, transactions become more complex, or compliance risk rises, bringing in a professional bookkeeper or accountant for periodic reviews is invaluable. You can continue using Beancount as your primary source of truth and simply export the reports they need.

Quick-Start Checklist​

• Open separate business bank accounts.
• Clone the Beancount starter repository and define your accounts in accounts.bean.
• Choose cash or accrual and stick to it.
• Set up importers to automate data entry from your bank (CSV), Stripe, PayPal, etc.
• Tag and write clear narrations for every transaction.
• Reconcile your ledger against bank statements weekly or monthly.
• Generate monthly income, balance, and cash-flow reports using Fava or bean-report.
• Back up your .bean files regularly (Git + off-site storage).

Further Reading​

• IRS Publication 583 — Starting a Business & Keeping Records
• Beancount Documentation — Language & Command-Line Tools

Ready to start? Install Beancount, commit your first entry, and trade spreadsheet fog for plain-text clarity. Happy bean-keeping!