Frequently Asked Questions

Is my financial data really private?

Yes. Beanie Budgets has no servers, no accounts, and no analytics. There's nothing set up to receive your data, so there's nothing for us to see.

What happens to my data if I stop using the app or delete it?

Your ledger is a folder of plain text files, which plenty of other beancount tools can open. Whether it survives deleting the app depends on where it is. A ledger in iCloud Drive, or in a folder you chose, sits outside the app and is left alone. A ledger kept only on your iPhone lives inside the app, so deleting the app deletes the ledger too. Copy it somewhere first.

If you're not sure where your ledger is, Settings names its folder. iCloud Drive is best if you want to open your ledger on a computer, since a Mac shows it in its own iCloud Drive folder.

Do you ever see my transactions or balances?

No. Everything is processed on your device only. We couldn't see your data even if we wanted to.

Is iCloud sync private too?

iCloud Drive encrypts your files while they're sent and while they're stored. For standard iCloud Drive, Apple holds the keys, so Apple could open your files if the law required it. Advanced Data Protection, in your Apple Account settings, makes them end-to-end encrypted so not even Apple can read them, where it's offered. Either way, Beanie Budgets is never part of that sync and never sees your data.

Is my data backed up?

Yes. Beanie Budgets saves a backup of your ledger before every change it makes. The backups are kept privately on your iPhone, not in the Files app, and are included in your iPhone's own backup to iCloud or your computer. Settings > Restore Backup goes back to any of the 20 most recent, so keep your own copy for anything older. A ledger in iCloud Drive is also synced and backed up by Apple.

Where can I keep my ledger?

On your iPhone, or in iCloud Drive. Beanie Budgets is built and tested for those two. Keeping it on your iPhone is simplest, and iCloud Drive syncs across your devices and is backed up by Apple.

You can choose another folder. One from Dropbox, or another app that keeps a real copy on your phone, usually works. A ledger on a network share or a server, reached over SMB or similar, isn't supported. The app reads every file in your ledger each time it opens, and a share can stop responding without saying so, which leaves the app waiting with no error. If you keep your ledger that way, work from a copy on your iPhone or in iCloud Drive, and sync that copy to the share.

How do I take my own copy of my ledger folder?

Your ledger is an ordinary folder of text files, so copy it as you would any folder. Settings shows where it is: in iCloud Drive, only on your iPhone, or in a folder you chose.

On your iPhone, open the Files app, find the folder, press and hold it, and choose Copy. A ledger kept only on your iPhone is under On My iPhone, then Beanie Budgets. Put the copy somewhere other than beside the original, since a copy in the same place shares whatever happens to it.

On a Mac, drag the folder to your Desktop or Downloads. If it's in iCloud Drive, don't duplicate it where it is: that often fails with "The operation can't be completed because an unexpected error occurred (error code -8062)". Your ledger is fine. macOS handles items in iCloud Drive differently from ordinary files, and duplicating a folder in place can fail without a useful message. Copying it outside iCloud Drive avoids that, and so does compressing it first (right-click, Compress) and moving the zip.

If you're comfortable in Terminal on a Mac, this copies your ledger to Downloads with the date in the name, and works when Finder won't. Type the first word and a space, then drag your ledger folder onto the Terminal window, which fills in its real path for you:

ditto <drag your folder here> ~/Downloads/ledger-backup-$(date +%Y%m%d)

The result is a plain folder you can open, zip, or copy anywhere. Run it again whenever you want a fresh snapshot, and the date in the name keeps them apart.

Why does my Mac show an older copy of my ledger than my iPhone?

iCloud Drive sometimes stalls on a file. In Finder, a file waiting to sync shows a dotted circle beside its name, and the Mac keeps its older copy until the file syncs. Don't open or edit that file on the Mac in the meantime. A save there can make the older copy look newer, and the change from your iPhone can go missing.

To restart iCloud Drive on the Mac, open Terminal and run this. It stops the Mac's iCloud Drive process, which starts again by itself, and a stalled file usually syncs within a minute or two:

killall bird

If a change still goes missing, Settings > Conflicts lists any version iCloud set aside, and Settings > Restore Backup goes back to a copy from before a change.

What is beancount, and do I need to already know it?

Beancount is a plain text format for double-entry bookkeeping: each transaction records where money came from and where it went. You don't need to know it. Setting up gives you a working ledger without typing any beancount. Beanie Budgets is an independent app, not affiliated with or endorsed by the beancount project.

Can I use my existing beancount ledger?

Yes. Choose the folder it's in, and Beanie Budgets reads and writes your files directly, with nothing to import or convert.

What files and folders does Beanie Budgets add to my ledger?

Almost nothing until you save something. Opening your ledger, looking at balances and running reports change nothing. The first time you save something, Beanie Budgets adds the file it belongs in: add a transaction and a file for that year appears, add a note and a notes file appears, set a budget and a budgets file appears.

One small exception. While the app has your ledger open, it keeps a file saying this device has it open, which is how your other devices show the "also open on..." warning. The file holds a device name and a time, and is deleted when you leave the app. So even a ledger you only look at gains a "beanling" folder with an empty "activity" folder in it.

Everything the app saves goes in that "beanling" folder, next to your main file. Most of it is ordinary beancount, which any beancount tool can read: transactions by year, budgets, balance corrections, accounts, notes and credit card auto-pay. A few JSON files hold things beancount has no syntax for: Plan Assumptions, saved Financial Planning scenarios and, if you share a ledger, the activity log behind the "also open on..." warning. Only those JSON files are safe to delete on their own. They hold no transactions, so deleting one just loses what it stored.

To make those files part of your ledger, Beanie Budgets adds an include line to your main file for each one, the first time it's needed. Over time you may see:

• include "./beanling/2026.bean", and one more for each year you record transactions in
• include "./beanling/accounts.bean"
• include "./beanling/balance-corrections.bean"
• include "./beanling/budgets.bean"
• include "./beanling/credit-card-autopay.bean"
• include "./beanling/documents.bean", with the files you attach in beanling/documents
• include "./beanling/notes.bean"

Anything you add in the app goes into one of those files, never into yours. Your own files change only when you edit, delete or rename something already in them, when an import replaces history it covers, or when you agree to move an account's opening date earlier. The app backs up the whole folder before each of those changes, and you can go back from Settings > Restore Backup. A new ledger you haven't saved anything to has no backups yet, since backups are made before changes.

The include lines are ordinary beancount, so your ledger still works in Fava or at the command line, and you can move them anywhere in the file.

Don't delete the "beanling" folder or the .bean files in it. They hold real transactions, and your main file includes them, so deleting them loses those entries and leaves include lines pointing at missing files. That stops your ledger opening in any beancount tool. If you want them gone, delete the matching include lines too, knowing that what was in them goes as well. Copy the folder first.

Can I share a ledger with someone else so we can both input transactions?

Yes. A ledger is a folder of plain text files, so you can share it through iCloud Drive like any folder. It isn't built for editing at the same moment, though. Each device picks up the other's changes when the app comes back to the screen, or when you tap Refresh Ledger in Settings, not while both are open. If you both edit the same entry at once, iCloud Drive decides which version wins, not the app. Beanie Budgets warns you when the ledger is open on another device, so taking turns is easy. See the next question.

Can I edit my ledger by hand while Beanie Budgets is open?

Yes, as much as you like. Just not while the app has the same ledger open on another device, because nothing can merge the two.

The "also open on..." warning only knows about other copies of Beanie Budgets. A text editor, Fava or any other beancount tool won't trigger it.

If the two do clash, it isn't obvious. iCloud Drive settles a clash one file at a time, and the last save wins. So if the app has just renamed an account across your ledger and you then save a file your editor opened beforehand, that one file loses the rename while every other file keeps it. Balances look wrong and the same account appears under two names, with nothing saying why.

To avoid it, close Beanie Budgets before editing by hand, let your files finish syncing, then reopen it. Just reading your files is always safe. And the app backs up the whole folder before every change it makes, so Settings > Restore Backup can put things right.

What's the "also open on..." warning about?

If you share a ledger, Beanie Budgets tells you when it's open on another device right now, so you can check with the other person before you both change something. It's a warning, not a lock: there's no server to enforce one. It relies on both devices' clocks being right, which they normally are automatically.

What if I don't have a ledger yet?

Choose "New to this?" when you set up, and Beanie Budgets creates a starter ledger for you.

Does it work with beancount v2 or v3?

Both. Beanie Budgets reads the beancount file format itself rather than running beancount, so there's no Python or plugins inside the app, and nothing to update when you upgrade beancount.

That's tested, not assumed. Test ledgers covering costs, prices, lots, foreign currencies, pad and balance, and holdings with no price are run through beancount 2.3.6 and 3.2.3, and the app's figures are checked against both. The two versions agree on every case. Version 3 changed the tools around the format, such as bean-query moving to the separate beanquery package, not the format itself.

The official project lives at github.com/beancount/beancount. Worth naming, because a web search can land you on other sites that are not the project itself.

Does it support multiple currencies?

Yes, with one currency shown at a time. Each account can hold its own currency. Overview and the Journal show one currency at once, with a button at the top left to switch. If your file sets an operating currency, with a line like option "operating_currency" "USD", the app opens on that, as Fava does. Otherwise it picks the first alphabetically, so set one if you use more than one currency. Beanie Budgets never adds different currencies together, and each Financial Planning scenario uses a single currency.

One exception, for what an investment is worth. Say you hold something priced in another currency, such as a US fund in a sterling ledger, and your file gives the exchange rate as a price directive. Holdings then uses that rate to show the holding in your operating currency. Only rates you've written are used, nothing is fetched, and only when your file sets an operating currency.

Overview shows such a holding at its cost, in the currency it was bought in. The cost was converted at the rate on the day you bought, and its value would be at today's rate, so mixing the two would count the rate change twice. So a foreign holding shows its cost on Overview and its value in Holdings.

Will it read my ledger, whatever I've written in it?

Very likely, and that's been tested. The app's parser is checked against the valid examples in beancount's own parser tests, each confirmed with bean-check first. It's also checked against a 6,600-line ledger from beancount's bean-example tool, where it finds the same 1,207 directives beancount does. Speed is tested on a made-up ledger of 39,000 transactions over 21 years, so a long history still opens quickly. The most useful testing has been people trying their own ledgers and telling us what broke.

Which beancount syntax does it actually understand?

• Transactions with payees, narrations, tags, links and metadata.
• Postings with amounts, or with the number or currency left out for beancount to infer.
• Arithmetic in an amount, like "100.00 + 5.00" or "(4.00 + 1.00) * 3".
• Cost bases and price annotations, preserved exactly as written and used to value a holding in money rather than in units.
• Account open and close, including a booking method like open Assets:Brokerage "FIFO", balance assertions including ones with a tolerance, pad, and note.
• Repeating transactions written the forecast plugin's way, as a "#"-flagged transaction tagged [MONTHLY UNTIL 2027-01-01] or [WEEKLY REPEAT 12 TIMES].
• Splitting a ledger across files with include, wildcards included.
• pushtag, poptag, pushmeta and popmeta.
• Fava's budget and fava-option custom directives.
• Windows line endings, a byte order mark, tabs and comma thousands separators are all handled.
• Price directives, used to value holdings at what they're worth.
• Commodity directives, for a holding's name and asset class.
• Document directives, which aren't displayed yet but are kept correct if you rename an account.
• Event and query directives, and custom directives of a type the app doesn't define, are recognised and skipped, so a file containing them opens normally and nothing is lost.

None of it stops your ledger opening. A line the app can't read is skipped. If it was something the app needed, most likely a budget, Settings lists it with its file and line number. Lines it skips on purpose aren't listed, so the ones that need attention don't get buried.

Can I record buying shares?

Not as units with a cost basis. Beanie Budgets reads those transactions, values the holding from your price directives, shows it in Holdings and counts it in your net worth, and leaves your lines as you wrote them. It can't create or edit them.

There's a simpler way that suits a phone, and many people use it. Record the money going in as an ordinary transfer from your bank to an investment account. Then use Correct Balance to set the account to what your provider says it's worth. You get the balance, the trend and your net worth without recording any lots. If you do keep lots, keep writing them where you do now, and the app will read them.

We may add this later, probably in a version for a bigger screen. Choosing lots and typing costs suits a keyboard better than a phone.

Why does a transaction show Delete but no Edit?

Because the edit form can't show it without changing what your file says. That happens with a transaction in more than one currency, one that balances through a cost basis, or one with an amount left for beancount to work out. The form works in one currency with amounts that add up to zero, so editing a share purchase there would turn your units into money. The app offers Delete instead and leaves the transaction alone. You can still change it in a text editor.

If I wrote an amount as a sum, does it stay a sum?

Yes, unless you change that amount. "100.00 + 5.00" shows as 105.00 in the app, and if the app ever rewrites that transaction, it writes your sum back exactly as you typed it.

If you edit the amount, the sum is replaced by the figure you enter, since the old sum would no longer match. The app never rewrites a sum or guesses a new one.

You can't type a sum in the app: amount fields take digits only. Write sums in a text editor, and the app will keep them.

Ordinary amounts are kept as you typed them too, so "40 VTI" stays "40 VTI" rather than becoming "40.00 VTI".

What happens when I close an account?

From version 1.8, Beanie Budgets follows your close directives as beancount does. Nothing can be added to an account after its close date, so recurring payments and card auto-pay stop there. A closed account drops out of the account lists, and once it's empty it's hidden from Overview unless you turn on Show Closed Accounts in Settings, Accounts. A closed account that still holds money stays on Overview, so the totals still add up.

You can close an account in the app too, from Edit Account, which writes the close line for you and can reopen the account later. The closing date can't be before the account's last transaction.

What doesn't it handle yet?

A few things. Document directives are kept correct when you rename an account, but the files they point to aren't shown. A holding priced in another currency is shown in your ledger's currency only if you recorded what it cost, as beancount does. Otherwise Overview lists it under Held, Not Priced, with its units. If you moved an investment in without recording what it cost, Holdings shows what it's worth, but Overview leaves it out of your totals, since there's no cost to count. And a foreign holding's balance stays in the currency it was bought in, as explained under multiple currencies.

Transactions that don't add up to zero are shown rather than refused, so a file you're part way through editing doesn't lock you out. A warning appears, and Settings lists each one with the amount it's out by and where to find it.

Where does the app tell me something's wrong with my ledger?

Settings, under Ledger. It shows which file is loaded and how many entries were read, then a line for each kind of problem you have:

• Transactions that don't balance. Beancount refuses a file with one of these, so any total including it disagrees with what beancount or Fava would say. Tap through for the list, each with the amount it's out by and the file and line to find it at.
• Lines that couldn't be read. Something Beanie Budgets tried to read and couldn't, most often a budget written in a form it doesn't recognise. The line doesn't appear in the app, and nothing else in the file is affected.
• Accounts that open later than a transaction in them. Beancount treats that as an error. That line offers to move those opening dates earlier, tells you how many will change before it does anything, and takes a full backup first.
• Balance assertions that don't match, and any error from loading the file itself.

The first two also show a dismissible notice at the top of the app the first time, so a real problem doesn't sit in Settings waiting to be discovered. Nothing here interrupts you with a pop-up, and nothing changes your files on its own.

What if my ledger won't open?

Please tell us. The error names the exact line in your file, and that line, with the amounts changed if you'd rather, is usually all it takes to reproduce and fix. Every compatibility fix so far has come from someone doing exactly that.

Do I have to record every single transaction?

No. You can record only what matters to you, then use Correct Balance from time to time to bring an account to what your bank says. Beanie Budgets adds a balance correction to cover the difference, so your balances stay right without every purchase being entered. It also spots transactions that repeat and offers to turn them into a recurring series, and Auto-Clear records your credit card payment in your ledger on the day it's due, so you don't have to. The more you record, the more your spending reports can tell you, but you don't have to enter everything.

How can I start my ledger again?

In Settings, tap Re-run Account Setup. It takes you back through account setup on your existing ledger, so you can rework your accounts without losing any transactions.

How do I delete an account I no longer need?

If you've stopped using it, close it instead, from Edit Account, which keeps its history. To remove it completely, tap Re-run Account Setup in Settings, swipe the account left and tap Delete. That removes the account and everything ever posted to it, so only do it for an account you're sure you don't need.

What's the difference between free and Pro?

Free covers everything that reads your ledger back to you: balances, budgets, recurring transactions, reports, loans and mortgages, your savings rate, and your holdings with their cost and value. All of that comes from your own file, so it stays free.

Pro adds what isn't in your ledger, where the app models something for you. That's all of Financial Planning and the years-to-independence projection, plus three investment reports. Investment Returns measures how your portfolio has done. Benchmark Returns sets each of your years against decades of market returns. Asset Allocation compares how your holdings are split with the split you're aiming for. Pro also adds the projections in Emergency Fund, Savings Rate and Growth, plus budgets across several accounts, budgets for an event such as Christmas, opening and attaching documents such as receipts, your own datasets, more than one ledger, more themes, featuring more than one chart or balance on Overview, and Stealth Mode.

Is Pro really one-time, not a subscription?

Yes. Pay once and keep it. No subscriptions, ever.

What happens to Pro if I get a new phone?

Sign in with the same Apple ID and tap Restore Purchases in Settings. Your Pro unlock comes straight back, no need to buy it again.

Why did a "Balance Padding" transaction appear dated the day before I corrected my balance?

That's a beancount rule, not a bug. Beancount only applies a correction dated before the balance it fixes, so the app dates it the day before.

What's the difference between a correction and a real transaction?

A real transaction records money actually moving between accounts. A correction brings your recorded balance into line with the real one, for an opening balance or a stretch you didn't track. Use corrections now and then, not instead of recording what happens.

What does the Conflicts screen in Settings mean?

From version 1.8. When a file in your ledger changes on two devices before they sync, iCloud keeps both versions. Sometimes it makes a numbered copy, such as main 2.bean, and sometimes it sets one version aside out of sight. Your ledger reads only one of them, so a change can go missing. Conflicts lists these. It also lists any file Beanie Budgets made that your ledger has stopped reading, which you can add back by tapping Include in Ledger, and any account your ledger opens twice. A banner tells you when there's something to look at.

I already use the forecast plugin for repeating transactions. Does that still work?

Yes, with nothing to convert. A transaction flagged "#" with a tag in brackets at the end of its narration is read as a template, and Beanie Budgets creates each occurrence from it, as the forecast plugin does. It understands DAILY, WEEKLY, MONTHLY, QUARTERLY and YEARLY, with UNTIL 2027-01-01 or REPEAT 12 TIMES. With neither, it uses five years, as the plugin does.

The occurrences appear in balances, reports and charts, but are never written to your file, so your template stays the one line you wrote. If a tag would create an unlikely number of occurrences, the series is capped and you're told.

This is different from the app's own Recurring switch, which writes real dated transactions into your ledger. Both work in the same file.

The app reads these templates whether or not your ledger turns the plugin on. If beancount shows fewer occurrences than the app, add plugin "beancount.plugins.forecast" to your ledger and they'll agree. Beancount 3 no longer includes the forecast plugin, so a ledger that names it shows an error there. The app's figures match beancount 2, or beancount 3 with the plugin installed separately. Series made with the app's Recurring switch are ordinary transactions and read the same in both.

How do I set up a recurring transaction?

Add a transaction as usual, then turn on Recurring before saving. You then choose a Start Date, an End Date, a Frequency (Daily, Weekly, Monthly or Yearly) and Every, to repeat at a multiple of it: quarterly is Monthly, every 3. Weekend Adjustment moves an occurrence that lands on a weekend to the Friday before or the Monday after, so it matches your bank statement.

Choosing a frequency sets a sensible End Date until you pick one yourself. If a range would create too many occurrences to save at once, you're told.

Beanie Budgets writes a real, dated transaction for each occurrence, not a rule. Each is ordinary beancount that any tool can read, and you can edit or delete any one of them.

To change a series later, open any transaction in it. Show Series lists every occurrence. Edit Series changes this payment, every upcoming one, or the whole series. Extend Series adds more occurrences. Delete This Series removes it all, or from a date you choose.

If repeating transactions are already in your ledger, open one and choose Make Recurring, or let detection find them, as the next answer explains.

How do I budget for Christmas, or another event?

With Pro, tap +, choose Add Budget, then Event. Give it a name, such as Christmas 2026, and a total, then add each person or item with their own amount. The items can add up to less than the total, to leave room for wrapping and food.

When you add a transaction, choose the event under Budget, and the person or item it's for. That tags the transaction, for example #christmas-2026, and records who it's for as budget-item: "Mum". It counts whichever account you paid from, so gifts bought by card and from your current account add up together. To count a transaction you've already added, open it, tap Edit and choose the event.

The event shows first on the Budgets tab with what you've spent of its total. Tap it to see what's left for each person or item, and every transaction tagged with it. Any transaction carrying the tag counts, including ones you tag by hand or with pushtag. The event is saved in your budgets file as ordinary beancount.

Is there a home screen widget?

Yes, free. Press and hold your home screen, tap Edit, then Add Widget, and choose Starred Cards. The small size shows the first card you've starred on Overview, with a line across your default date range from Settings, dashed beyond today where it's a forecast. The medium size adds the next three beside it. Your net worth appears only if you've starred it.

The widget doesn't read your ledger itself. It shows the figures from the last time Beanie Budgets opened your ledger, with that date, so open the app to bring them up to date. With Stealth Mode on, the widget hides the amounts, though the line still shows their shape. The demo isn't shown on the widget.

Can I keep receipts and statements with my transactions?

With Pro, yes. When you add or edit a transaction, choose Attach Photo or Attach File under Documents. Beanie Budgets saves the file in your ledger folder, under beanling/documents and then the account's name, named from the transaction's date as beancount names a document, for example 2026-11-02.receipt.jpg. It writes a document line for it in beanling/documents.bean, sharing a ^link with the transaction, which is how beancount and Fava tie the two together.

To file a document from another app, such as a statement attached to an email, tap Share and choose Beanie Budgets, then pick its account and date. If your ledger names a folder with option "documents", the file goes there under the account's name, where beancount finds it without a line; otherwise it goes under beanling/documents. To file the email itself, tap Print, then Share, which saves it as a PDF.

A transaction's documents show on its own screen, and an account's on its transactions screen under Documents. Tap one to open it. Documents you already keep are shown too: any document line, and files in a folder your ledger names with option "documents", laid out by account and named from their date, as beancount finds them. Attached files aren't copied into the app's backups, so keep your own copy of the ledger folder.

How does recurring-transaction detection work?

Beanie Budgets looks for transactions with a similar payee and amount repeating on a regular cadence and offers to make them a recurring series, so the app adds the future payments for you.

My investments are recorded in stock symbols rather than money. Does that work?

Yes. A holding written the usual beancount way, like 10 VTI {50.00 USD}, counts as 500.00 USD alongside your cash, and totals, charts and reports all use that figure. A line beneath it reads "10 VTI at US$50.00", so the units and price are still shown.

Other ways of writing a purchase work too. A price rather than a cost, like 10 BND @ 20.00 GBP, is a holding. So are units transferred in from another provider, and a cost written as a sum, like {20.00 / 2 USD}, is read as 10.00. Units transferred in with no cost show their value, and say there's no gain to show, rather than counting the whole value as profit.

For a sale, the lot it names sets the cost. If it names none, your file's booking method decides: on the account, as open Assets:Brokerage "FIFO", or for the whole ledger with option "booking_method" "FIFO". All five of beancount's methods are read (FIFO, LIFO, HIFO, AVERAGE and NONE), and with none set the oldest lot is used. With AVERAGE, the app works out an average where beancount would refuse a sale it can't match to a lot. Your file is never rewritten by any of this.

Add price directives and Holdings also shows what each holding is worth today, and the gain. Prices come from your own file, often written by beancount's beanprice tool. The app never fetches a price: there's no network request anywhere in it. A holding priced in another currency follows an exchange rate from your file, when your file sets an operating currency. Overview shows that account at its cost, as explained under multiple currencies.

Holdings is free, and lists everything you hold with its cost, value and gain.

Why don't I see a separate Capital Gains Unrealised line under my account?

Because beancount counts it as part of the account. A balance on Assets:Investments:ISA includes everything under it, so £58,917 in the account plus £21,421 in its :Capital-Gains-Unrealised sub-account is a balance of £80,338 to beancount and Fava. Beanie Budgets shows the same £80,338. It used to show only the £58,917, which disagreed with beancount, and confirming that figure with Correct Balance would quietly have wiped out your gains.

So a holding shows as one account at what it's worth, with its contributions and gains together in its transactions. The same goes for a :Valuation-Adjustment sub-account, which a defined benefit pension uses to record new transfer values.

The split between what you put in and what it grew by is in the Realised Gains and Unrealised Gains reports. The sub-accounts stay in your ledger as written.

What are unrealised and realised capital gains?

An unrealised gain or loss is the paper change in something you still hold. A realised gain or loss is the actual profit or loss once you sell. Beanie Budgets tracks them separately, so your income reports count only what you've actually made.

Where does Beanie Budgets record capital gains, and does it work with how I already do it?

There are two common ways to handle gains in beancount. Beanie Budgets uses one and reads both.

How Beanie Budgets records them. A gain goes in a sub-account of the holding:

• Assets:…:<your account>:Capital-Gains-Unrealised, funded from Equity:Unrealised-Gains
• Assets:…:<your account>:Capital-Gains-Realised, funded from Income:Capital-Gains-Realised, or Income:Capital-Loss-Realised when it's a loss

Realised gains and losses have separate accounts, so one can't hide the other. An unrealised gain uses one account whichever way it moves, and is booked to Equity rather than Income, because a paper change isn't money earned. Beancount's own unrealized plugin uses the same kind of sub-account, labelled Unrealized by default, and Beanie Budgets recognises both spellings.

The other way: holdings at cost, with prices. If you record units at cost, like 10 VTI {50.00 USD}, with price directives, unrealised gains aren't recorded at all. They're worked out as today's value less what you paid. A realised gain is the balancing line of the sale itself. Beanie Budgets reads all of that.

Can a ledger use both? Yes, in different accounts, and the Unrealised Gains report shows each. Avoid using both in the same account, as the same gain is then counted twice. The app doesn't choose between them for you, but it names the account so you can fix it.

Which should you use? If an investment is a money figure you update, use the sub-account approach, since there are no units or prices to work from. If you hold units at cost, the second approach is less work. The app can't type a cost basis, so you'd write those purchases and sales in a text editor, and the app reads them.

How are dividends and interest counted towards an investment's return?

From version 1.8, as part of the return, wherever they were paid. Investment Returns shows how much of each account's return came from dividends and interest, and on Growth you can tap Dividends And Interest to see which accounts earned them.

Beanie Budgets counts a dividend towards the investment named in the income account you record it under, even if the money was paid into your brokerage's cash or your current account. Income:US:ETrade:VHT:Dividend belongs to Assets:US:ETrade:VHT, and Income:Dividends:VWRL to the one account ending in VWRL. If it names no holding, as a plain Income:Dividends doesn't, the dividend counts towards the account it was paid into. If that account is outside your investments, it isn't counted.

How do I record something that needs more than two accounts, like moving an investment to a new provider?

Most entries are simply one account paying another, which is what "Paid From" and "Paid To" are for. Some need more than two: a pension contribution split between employer and employee, a mortgage payment split into interest and principal, or an investment moving to a new provider. On Add Transaction, open Advanced and tap "Add Another Posting" to list each account on its own line, with its own amount, positive or negative. The running Balance at the bottom has to reach exactly zero before it can be saved, which is your check that nothing has been lost or invented along the way.

A provider transfer is a good worked example, because it is not a sale. Nothing is realised, so the unrealised gains you have built up travel across with the holdings instead of vanishing and reappearing. Suppose the old account holds 40,000.00 of contributions with 10,000.00 of unrealised gains recorded beside it, and you move everything except 100.00:

• ISA, new provider: + 39,900.00
• ISA, old provider: − 39,900.00
• Capital Gains Unrealised, new provider: + 10,000.00
• Capital Gains Unrealised, old provider: − 10,000.00

Every line is one of your own accounts, so nothing touches income or equity. That is the point: this is a move, not a gain. You may need to create the new provider's own Capital Gains Unrealised sub-account first, either from Manage Accounts or with the "Add New Account" shortcut in the account picker.

If your new provider's own figure differs a little once the transfer lands, that gap is real market movement rather than part of the transfer, so record it on its own with Correct Balance on the new account and "Track as Unrealised Capital Gains". Following the example above, if the provider says 49,880.00 where your ledger now says 49,900.00, set the new gains account to 9,980.00 and the 20.00 difference is recorded as an unrealised loss.

One handy trick if the Balance refuses to reach zero: when it lands on exactly twice one of the amounts you typed, that line has the wrong sign.

How do you auto-populate a figure like my monthly savings and investments?

From your ledger. A Financial Planning scenario's starting balance comes from the accounts you select, and your monthly contribution from what you've actually paid into them. The app fills in other forms the same way: loan terms from a mortgage account, target spending from your average spending, and account suggestions from what you use most. Each fills in an ordinary field you can change before saving, and nothing is written to your ledger.

Is any of this financial advice?

No. Beanie Budgets' models are for information and education only. Their results are illustrations based on your assumptions, not predictions or advice. You're responsible for your own decisions, so consider speaking to a qualified adviser before acting. See the full Disclaimer.

Are the figures in today's money, or what I'd actually see in the future?

Today's money. Every Financial Planning projection allows for inflation, so £500,000 in twenty years means £500,000 of today's buying power. A statement then would show a bigger number, but it would buy the same things. The historical datasets are already real returns, and a series you import in nominal figures is converted year by year using that market's inflation.

Why do savings default to 0% growth?

Because the figures are in today's money. 0% means your savings keep pace with inflation, so their buying power stays the same, which is roughly what cash has done over the long run. Anything above 0% is growth above inflation: if prices rise 3% and an account pays 5%, enter 2%.

Do I need to increase my target retirement income for inflation?

No. Enter what you'd want to live on if you retired today. The projection keeps that amount level with prices every year. Adding inflation yourself counts it twice and makes the plan look far worse than it is.

What are Go-Go, Slow-Go and No-Go?

Three stages of retirement spending. Many people spend most in the early, active years, often on travel: the Go-Go years. Spending tends to ease as they slow down in the Slow-Go years, and in the No-Go years it is mostly at home, though care costs can push it back up.

In Plan Assumptions, Target Income in Retirement starts as your Go-Go figure. Add a Slow-Go or No-Go stage with the date it starts and its own annual target, and the reports step your target down on those dates. Leave both off and one figure applies for the whole retirement.

Is anything shown in future money?

The Drawdown Tracker. Its Portfolio Drawdown is the pounds you'd actually take in the coming year. At each check-in you enter published inflation since the last one, and most models raise your withdrawal to match. Guyton-Klinger skips the increase after a year your portfolio fell. Models that work from your portfolio, such as Percent of Portfolio, use inflation only to bring last year's figure up to today's prices. For a forecast in future money, Growth Forecast lets you enter a rate before inflation.

Which withdrawal models are there, and how do they differ?

From version 1.8 there are eight. Some keep your income steady, some spend as much as the portfolio allows, and some aim to make the portfolio last. Before that there were three: Safe Withdrawal Rate, Guyton-Klinger and Risk-Based. For steady income, the Safe Withdrawal Rate keeps your spending fixed, adjusted only for inflation, for the whole plan, and the Ratchet does the same but raises it when the portfolio has grown well past where it started, and never cuts it.

To spend as much as the portfolio allows, Percent of Portfolio takes the same share of whatever it holds each year, and Variable Percentage Withdrawal sets a share that would last until you're 100 if you've set your year of birth in Plan Assumptions, or until your plan ends if not, so the share rises each year. Both move with the markets.

For a portfolio that lasts, Ceiling and Floor takes a share of the portfolio but limits how far each year's spending can rise or fall, Endowment bases most of each year's spending on last year's and the rest on what the portfolio holds now, so it changes slowly, and the two guardrails models, Guyton-Klinger and Risk-Based, review your spending each year and adjust it up or down based on how the portfolio is doing. In Retirement Model, every one keeps your spending at or above your Essential Income, if you set one.

Why does the Withdrawal chart sometimes have shading only above the line?

Once your pensions and other income have started in your plan, your portfolio only attempts to pay the part of your spending the other income sources don't cover. If that part is small, your portfolio is under little strain in almost every modelled sequence.

Shading above the line comes from sequences where you are able to take more than the median. The model may raise your spending when markets do well for example. And if a pension's yearly increase is capped, inflation above the cap means that pension buys less, so you need more from your portfolio.

Shading below the line needs sequences where you take less than the median, which mainly happens when your model cuts your spending. If your portfolio is under little strain, cuts are rare, so there may be nothing to draw below the line.

Why does the Withdrawal chart show a slightly different withdrawal from Income Over Time?

The two charts show the same withdrawals in different ways. Income Over Time shows each month on its own, so you can see income sources starting part way through a year. The Withdrawal chart shows each plan year's average, as your withdrawal model reviews your spending once a year.

So a single month on Income Over Time can be a little above or below the year's average on the Withdrawal chart. Neither figure is wrong.

Can a plan that lasted through every past sequence still run out?

Yes. Backtests replay the returns and inflation in their dataset. The future can be worse than any period in that data, so a plan that would have lasted through every past sequence can still run out. Synthetic datasets are generated rather than real history, and a dataset from another country may not reflect returns or inflation where you live.

What do "Single Path" and "All Sequences" mean?

All Sequences runs your plan from every starting year in the dataset at once, showing the range of outcomes. Single Path follows one starting year, so you can see how that stretch of history would have played out.

What does a percentile, like the 50th percentile, actually mean?

Our models rank every sequence from worst to best. The 50th percentile, the median, is the middle one: half did better and half worse. The 5th is a bad outcome and the 95th a good one. The charts' 9 in 10 band runs from the 5th to the 95th.

How is each year in Model Data worked out?

The first year in Model Data starts from your portfolio on the day you start drawing on it, after all the contributions and growth before then. It counts only what you can spend, so a pension you can't reach yet joins the balance when it unlocks, and the Note column says so.

From there the model works a month at a time: each month it takes that month's withdrawal, then grows what's left. Doing it in one yearly step gets close, but not to the penny, because money withdrawn in January doesn't earn that year's returns.

Two things catch people out when checking a year of Model Data by hand. Where your plan has tax, Withdrawal Before Tax is what leaves your portfolio, Estimated Tax is the year's tax, and Total Income After Tax is what you receive, so each row adds up. Without tax the Withdrawal column is what you receive, so with a Tax Adjustment your portfolio pays out more than that. And a plan year starts in the month you start drawing, not in January, so a year labelled 1989/90 covers parts of both calendar years. That's why there are two return columns. Calendar Return is the calendar year's figure, which you can check against published history. Period Return is what that plan year's twelve months actually returned, so use that one to check a year's figures.

The Note column explains anything unusual in a year, such as a mortgage being paid off, a pension becoming available, an income starting, or a withdrawal held back by a rule.

Why is the Period Return in Model Data so different from the Calendar Return beside it?

Because a plan year isn't a calendar year. Unless you start drawing in January, each plan year in Model Data spans parts of two calendar years, and Period Return combines them. When two neighbouring years were very different, the two columns can look nothing alike.

For example, start drawing in September, and about a third of each plan year is the year it's labelled with and two thirds the next. If the labelled year gained 25% and the next lost 25%, Model Data shows a good Calendar Return beside a negative Period Return. A different start month weights the years differently, so the same history gives different Period Returns for different plans.

When neighbouring years are similar, the two columns nearly agree. Period Return is the figure that reconciles the balances, and Calendar Return is there so you can check against published history. If you start drawing in January the two are the same, and Period Return is left empty.

Why does a model's own figure sometimes differ from what my plan withdrew?

Usually because something else took over that year: your Essential Income floor, a maximum, or your portfolio running low. Model Data's Note column says which.

Does the Drawdown Tracker include tax?

Yes, once you've set up tax in Settings > Tax. The tracker works out tax on each year's withdrawal the same way Retirement Model does, counting your other income and any tax-free amount, so Portfolio Drawdown Before Tax is what to take out of your portfolio. It shows the estimated income tax, and the estimated capital gains tax where an account is taxed on its gains. Where it has to estimate, such as inflation still to come, the tax can differ a little from what you'll actually pay.

What's the "Essential Income" floor?

It's the least you've said you need to live on. In Retirement Model and the Drawdown Tracker, no model takes your withdrawal below it, even in a bad year, after counting what your pensions and other income already pay. Withdrawal Models leaves it out, so its results compare like for like with other calculators.

Why is the National Insurance in the Income Tax Model a few pence different from my payslips or another calculator?

Because the model works out National Insurance on a whole year at once, using the annual thresholds. Employers work it out on each pay period, using weekly or monthly thresholds that are rounded versions of the annual ones, so the year's total comes out a few pence different. On a £60,000 salary, the annual figure is £3,210.60, paid weekly it comes to £3,210.32, and paid monthly to £3,210.00. Income tax is unaffected, and so is anything a plan decides, since the difference is pennies a year.

Can a couple be taxed together?

Yes, from version 1.8, in Advanced tax, for countries where a couple can be taxed as one, such as married filing jointly in the US, or joint assessment in Germany and Ireland. With Include Partner Income on, turn on Taxed Jointly and enter the bands your country sets for a couple. Both of your income sources, withdrawals and gains then go through those household bands. Contributions charged on earnings, such as National Insurance, are still worked out for each of you separately. In the UK, where each person is taxed separately, leave it off.

Can I model required minimum withdrawals?

Yes, from version 1.8, in Advanced tax, under Required Withdrawals. This is for countries that require a minimum amount to be drawn from retirement accounts each year, such as required minimum distributions in the US, RRIF minimums in Canada and superannuation minimum drawdowns in Australia. Add a step for each change: the date it starts and the share of your income-taxed accounts that must be drawn each year, for example 4% from 2052, matching your country's table at the ages that apply to you. If your plan's own withdrawals fall short, the rest is taken at the end of the year, taxed as income and reinvested, so only the tax leaves your portfolio. It applies throughout Retirement Model, including the years before your pension starts, but not in Withdrawal Models, which don't model tax.

Can I take a pension's tax-free cash a bit at a time, like UFPLS?

Yes, from version 1.8. This follows the UK's uncrystallised funds pension lump sum, where a quarter of each withdrawal is tax-free until your Lump Sum Allowance is used. In Edit Account, under Tax, set Tax-Free Amount to In Total and enter the allowance you have left, with the date it can be used from. Then choose Taken: Share of Each. The share starts at 25% and can be changed where your rules differ. Withdrawals come from your accounts in proportion to their balances unless you choose a Withdrawal Order, below.

Can I choose which accounts my withdrawals come from?

From version 1.9, in Retirement Model with Advanced tax. Withdrawal Order offers four fixed rules. Draw Down Proportionally From Every Account takes from every account by its balance, as before. Draw Down Tax-Free Sources First takes from accounts that aren't taxed as income, such as an ISA, before those that are, such as a SIPP. Draw Down Tax-Free Sources Last does the reverse. Draw Down Taxable Sources up to a band you choose, such as the 20% rate, takes from accounts taxed as income only until your income reaches the top of that band, then from the others. Whenever the others are drawn, accounts taxed on gains go first, up to the year's tax-free gains.

Your income sources, such as a DB pension or State Pension, are always paid in full and taxed first. A one-off payment, such as a mortgage payoff or a purchase, comes from money that isn't taxed as income first in every order, tax-free cash included. If they already fill the band you chose, drawing taxable sources up to it draws as Draw Down Tax-Free Sources First. The band starts at the lowest with room in any year of your withdrawals; a year without room draws as Draw Down Tax-Free Sources First. A tax-free amount taken all at once, such as a pension's tax-free cash, leaves the pension on the date it starts, and whatever you don't spend is assumed to be kept somewhere tax-free, such as an ISA or Premium Bonds. The model uses the tax-free amount you enter, even if it's more than a quarter of the pension, as protected tax-free cash can be.

To compare orders, run your plan in each. Target Income Achieved compares them best. Final Portfolio Balance counts what's left in taxable sources, such as a pension, before the income tax you'd pay drawing it, shown as In Taxable Sources, so an order that leaves more in them looks better than it is. Tax Paid Over the Plan doesn't compare either, as tax paid earlier also costs the growth it would have earned. The model leaves out inheritance tax, which can favour drawing a pension sooner, and choosing when to take a DB or State Pension. With Rebalance Each Year on, as it starts, the accounts are rebalanced each year to keep today's mix of investments. So every account grows at one rate, blended from each account's model data by its balance today, and the order changes the tax, not how the money is invested. With it off, tax-free, taxable and gains accounts each grow on their own accounts' model data, so drawing one first changes what is left invested too. The switch is offered where the plan uses Benchmark Data and the accounts don't all follow the same data. Income sources such as a DB pension are income, not money that can be moved, so they are never rebalanced.

Are dividends taxed?

From version 1.9, in Retirement Model with Advanced tax, for accounts taxed on gains. They pay dividends at the yield set in Settings > Tax > Capital Gains Tax Assumptions, 2% a year to start, taxed each tax year whether you spend them or not, after a tax-free amount and on top of your other income, as in the UK. What's left after tax is reinvested, so it adds to what you paid and lowers the gain taxed later. Interest on bonds or cash outside an ISA isn't taxed, and moving investments into an ISA each year to shelter them isn't modelled. The Drawdown Tracker taxes only what you withdraw.

Where does the historical market data come from, and how far back does it go?

From published market return series, such as the S&P 500 back to the late 1920s. Every backtest runs your plan from every starting year the dataset covers. Synthetic datasets are generated rather than real history, to test a plan against conditions history hasn't shown.

Can I bring my own market return data?

Yes, with Pro. Import your own historical series, or build a synthetic market with booms and crashes to stress test a plan.

How is "spare" or "unallocated" money each month worked out?

It starts with your income over the date range the screen is set to, averaged to a month, and takes four things off it.

• Pension contributions are not counted as income. They are income in double-entry terms, but you cannot redirect them, so counting them would offer you money you never see.
• Your real spending across every expense category, not what you budgeted.
• What you already put into savings and investments. Money with a job already is not spare.
• The capital part of any loan payment. A loan payment splits in two: the interest shows up as spending, but the part that pays the balance down never does, so it has to come off separately.

That's the figure. The app also forecasts your current accounts over the next six months from what's already in your ledger, and if spending that amount each month would take them below zero, with not enough in savings to cover it, it warns you when. A dip that stays above zero, or one your savings can cover, isn't a warning: a December of presents doesn't set your limit for the whole year.

This is why the figure can be zero even when your income is comfortably above your spending: the gap is already committed.

I imported one account. What happens to transfers to my other accounts, and does it matter if they are not in my ledger?

An export covers one account, so it carries only the transfers that touched that account and says nothing about what the account at the other end holds. We never guess. A transfer out waits in Equity:Unassigned-Transfers, which sits outside your net worth, until you import that account's own export and the two sides meet.

That means you do not have to do anything with transfers. Leaving them alone is the right answer rather than an unfinished job.

What it does depend on is whether your other accounts exist in your ledger with their own balances. Two cases:

• The other account is set up with its real balance. Everything is correct. That account's balance came from you, the imported account's balance matches the figure you confirmed, and your net worth adds up. The waiting transfers are a record of what has not been matched up yet, not money missing from the total.
• The other account is not in your ledger at all. Your net worth understates by whatever moved into it. The money left the account you imported and nothing in your ledger has claimed it, so it sits outside the total rather than in a holding you own.

So the advice during setup, to add every account you have along with its balance, is worth following before you import anything. It is also why the error only ever runs one way: an account you have not told us about makes you look poorer than you are, never richer.

My balance looks wrong, what should I check first?

Look for a balance correction in that account's transactions first, since it shows when the balance was corrected and by how much. Then look for a missing or duplicated transaction around the date the balance goes wrong.

One of my include lines is listed as not read. Why?

Because Beanie Budgets can only open files inside the folder you chose. iOS gives an app access to one folder, and nothing above it. So an include that points outside it, like include "../shared/accounts.bean", works in beancount on a computer but can't load here.

The rest of your ledger still loads. Settings lists the line so you know what's missing.

To fix it, keep all your files under one folder, with your main file at the top, and choose that folder. If your files are in folders side by side, put a main.bean in the folder above them that includes each one, and open that folder instead.

Beanie Budgets cannot read a line that beancount accepts. Is that a bug?

Yes, and we'd like to know. The app is checked against real beancount on thousands of generated ledgers, and against other people's grammars and specifications, but beancount is a big language and there will still be gaps.

Settings lists any lines the app couldn't read, each with a code. From there you can send us a report with those codes and the shape of each line, with your accounts, payees and amounts removed. Nothing leaves your iPhone unless you send it.

I found a bug or have a feature request, how do I reach you?

Email contact@beaniebudgets.com. We read every message.