As someone who runs a small consulting business and used to dread receipt management, I need to share how beancount.io v3’s document linking feature has completely transformed my workflow.
The Old Way (Pre-v3): Receipt Hell
Before v3, my receipt management was a disaster:
My chaotic process:
- Receive invoice/receipt (email, paper, screenshot)
- Save to Downloads folder (random filenames)
- Enter transaction in beancount file
- ???
- 6 months later, need receipt for audit → Can’t find it
The problem:
- Receipts scattered across: Email, Downloads, Desktop, Phone photos
- No connection between beancount transaction and physical document
- Tax time = panic searching for receipts
- Audits = nightmare
Year-end tax prep:
Me: "Where's the receipt for that $1,200 software purchase?"
*Searches email for 30 minutes*
*Checks Downloads folder - 500 random PDFs*
*Gives up, hopes IRS doesn't ask*
The v3 Solution: Automatic Document Linking
Beancount.io v3 automatically discovers and links documents in your Git repository to transactions.
How it works:
1. Save document to /documents folder in your repo
Your repo structure:
my-finances/
├── personal.beancount
├── business.beancount
└── documents/
├── 2025-01-15-invoice-acme-software.pdf
├── 2025-02-03-receipt-office-depot.pdf
└── 2025-03-20-contract-client-abc.pdf
2. Commit to Git
git add documents/2025-01-15-invoice-acme-software.pdf
git commit -m "Add Acme Corp software invoice"
git push
3. v3 auto-links based on date/amount
When you create this transaction:
2025-01-15 * "Acme Corp - Annual software license"
Expenses:Business:Software 1200.00 USD
Liabilities:CreditCard -1200.00 USD
v3 automatically finds 2025-01-15-invoice-acme-software.pdf and links it!
The Magic: Fuzzy Matching
v3’s algorithm:
- Date matching: Documents with dates matching transaction dates
- Amount matching (if PDF parseable): Links documents with matching amounts
- Filename keywords: Matches keywords in narration to filename
Example:
Transaction:
2025-02-20 * "Office Depot - Printer paper and supplies"
Expenses:Business:Office 85.43 USD
Liabilities:CreditCard -85.43 USD
Document: 2025-02-20-receipt-office-depot.pdf
v3 matches based on:
Date: 2025-02-20- Keyword: “Office Depot” in both
- Amount: $85.43 (if parseable from PDF)
Date: 2025-02-20Result: Instant link
My New Workflow
Before (30 minutes per receipt):
- Receive invoice by email
- Download PDF
- Rename file manually:
invoice-vendor-date-amount.pdf - Move to organized folder structure
- Update spreadsheet tracking invoices
- Enter transaction in beancount
- Manually note where receipt is stored
After (2 minutes per receipt):
- Receive invoice by email
- Save to
documents/folder (any filename works, but I use date prefix for sorting) git add documents/2025-*.pdf && git commit -m "Add receipts" && git push- Enter transaction in beancount (v3 web UI)
- v3 automatically links document → DONE
Time saved: 93%
Real Example: Tax Season
February 2025: Time to file 2024 taxes
The old way:
- Spend 2 weeks gathering receipts
- Search email for “invoice” (2,000 results)
- Dig through Downloads folder
- Call vendors to re-send invoices
- Still missing 20% of receipts
With v3:
# Generate expense report with all linked documents
beancount-query business.beancount "
SELECT
date,
narration,
cost(position) as amount,
account
WHERE account ~ 'Expenses:Business'
AND year = 2024
ORDER BY date
"
Every transaction has linked PDF - click to view immediately in v3 UI.
Tax prep time: 4 hours (vs 2 weeks)
Document Linking in v3 Web UI
When you view a transaction in the v3 web interface:
Transaction view:
2025-01-15 * "Acme Corp - Annual software license"
Expenses:Business:Software 1200.00 USD
Liabilities:CreditCard -1200.00 USD
📎 Linked Documents (1):
📄 2025-01-15-invoice-acme-software.pdf
[View] [Download]
Click “View” → PDF opens in browser
No more searching!
Supported File Formats
v3 links these document types:
- PDFs: Invoices, receipts, contracts
- Images: JPG, PNG (phone photos of receipts)
- Office docs: DOCX, XLSX (contracts, expense reports)
- Text: TXT, MD (notes, documentation)
My workflow for paper receipts:
- Take photo with phone
- Save to synced folder (iCloud/Dropbox → documents/)
- Auto-commits to Git when synced
- v3 auto-links
Advanced: Manual Linking
v3 auto-links most documents, but you can also manually specify document links in beancount syntax:
2025-03-15 * "ClientABC - Website redesign contract" ^contract-abc-2025.pdf
Assets:Receivable:ClientABC 15000.00 USD
Income:Projects:ClientABC -15000.00 USD
The ^contract-abc-2025.pdf syntax explicitly links the document.
Use manual linking when:
- Document name doesn’t match transaction date
- Multiple documents for one transaction
- Want to ensure specific document is linked
Version Control for Documents
Since documents live in Git:
Every change is tracked:
git log documents/2025-01-15-invoice-acme-software.pdf
See who changed what:
commit abc123
Author: patricia
Date: 2025-01-15
Add Acme Corp invoice
commit def456
Author: patricia
Date: 2025-01-16
Replace invoice with corrected version
Audit trail built-in!
Cloud Storage Integration
v3 works great with cloud-synced Git repos:
My setup:
~/Dropbox/my-finances/ ← Dropbox syncs
└── (Git repo)
├── business.beancount
└── documents/
Workflow:
- Receive invoice on phone
- Save to Dropbox/my-finances/documents/ from phone
- Dropbox syncs to Mac
- Automatic Git commit (via cron script)
- v3 auto-links
Phone → v3 linked in 30 seconds
Benefits Over Traditional Filing
Old system (physical files):
- Filing cabinet with folders
- “Where did I file this?”
- Can’t search
- No backup
- Lost in office fire/flood
Old system (digital folders):
- Nested folder structure
- “Was this in 2024/Q1/Software or Vendors/Acme?”
- Search by filename only
- No connection to accounting records
v3 Git + Document Linking:
- Flat structure (just /documents/)
- Connected to transactions
- Full-text search (if PDFs)
- Version control
- Cloud backup
- Accessible from v3 web UI anywhere
Compliance Benefits
For my business, I need to:
- Keep receipts 7 years (IRS)
- Provide receipts on demand (audits)
- Track expense categories (tax deductions)
v3 makes this trivial:
IRS audit request: “Provide all software expense receipts for 2024”
beancount-query business.beancount "
SELECT date, narration, cost(position), account
WHERE account ~ 'Expenses:Business:Software'
AND year = 2024
"
Result: List of all software expenses with linked PDFs
Click “Download All Documents” → Zip file with all receipts
Audit response time: 5 minutes (vs 2 days)
My Specific Use Cases
1. Client invoices (income)
2025-03-15 * "Invoice ClientABC - March deliverables" ^invoice-abc-2025-03.pdf
Assets:Receivable:ClientABC 5000.00 USD
Income:Projects:ClientABC -5000.00 USD
Link my own invoice (outgoing)
2. Vendor invoices (expenses)
2025-03-20 * "Acme Hosting - Q1 2025 hosting bill" ^invoice-acme-q1.pdf
Expenses:Business:Hosting 300.00 USD
Liabilities:CreditCard -300.00 USD
Link vendor invoice (incoming)
3. Contracts
2025-01-10 * "ClientXYZ - Annual retainer contract" ^contract-xyz-2025.pdf
Assets:Receivable:ClientXYZ 60000.00 USD
PARTIAL - v3 will link the .zip file, but can’t peek inside. I recommend extracting first, then linking individual files. Or link the zip if you want to preserve the bundle.
v3 can’t parse password-protected PDFs for amounts.