Income Refinery User Guide

Both versions share the same beautiful interface and all the core tracking features. Pro adds analytical depth — forecasting, scenario modelling, yield-on-cost tracking, and unlimited capacity, for investors who want to go further. See the Pro page for pricing.

These six steps are the same for both versions. You'll have your first income entry showing in just a few minutes.

Screenshot: Income Refinery Pro, Income Sources tab

Income Refinery Pro

Stocks · Bonds · Real Estate · All streams · One view

Settings

Analyse ▾

＋ Add income ▾

This Month

Average

Expected This Month

$4,280.50

Annual: $51,366 · 12 income sources · USD

Holdings: $2,840/mo

Property: $1,040/mo

Other: $400.50/mo

FI Target

$6,000/mo

$1,719.50 to go

71% of target

Adjust

FI Milestones

Lean FI (70%)

$4,200/mo ✓

Achieved today

Standard FI (100%)

$6,000/mo

~3.2 years · Aug 2029

Fat FI (150%)

$9,000/mo

~9.8 years · Mar 2035

JAN

$1,120

FEB

$480

MAR

$1,740

APR

no income

MAY

$920

JUN

$1,680

JUL

no income

AUG

$540

SEP

$1,680

OCT

no income

NOV

$480

DEC

$1,726

The Pro Dashboard

Pro opens on a Dashboard with two tabs: Dashboard and Income Sources. The Dashboard shows this month's expected income, your average monthly income, and your progress against your monthly target, with a 12-month income calendar below. Select a month to see what each source pays. Below the calendar, Financial Independence Projections show when you could reach Lean FI, Standard FI, Fat FI and Coast FIRE, using the Base scenario of your Forecast assumptions. In a custom target, the three levels show as percentages of your target. Further down, it splits your income across Stocks, REITs and funds, Property, and Other income, shows your snapshot progress, and links to the Forecast. Analyse (History, Forecast, What-If) and Settings sit in the top bar.

Click Manage income sources or the Income Sources tab to add and edit holdings, properties and other income. A small ← Dashboard control at the top of that page takes you back. The Dashboard reads your data and never changes it. Holding amounts are after withholding tax, and rental amounts are after costs. A source with no exchange rate is left out of the totals, and the Dashboard says so.

Screenshot: Income Refinery (Free), header

Income Refinery

Stocks · Bonds · Real Estate · All streams · One view

Settings & FX Rates

Live FX

Go Pro

The Lookup button tries eight sources in priority order, stopping as soon as it gets a result. The key message upfront: Yahoo Finance is the last resort, not the first. Set up any one better source and lookups become fast and reliable.

Click Settings in the Pro header, or Settings & FX Rates in the free header, to open the settings panel.

Your FI Target and US withholding settings are in the FI Target Drawer (Pro: click Set target or Adjust target on the Dashboard, or Adjust in the hero on the Income Sources tab) or directly on the hero panel (free).

Screenshot: Settings panel, Appearance & FX sections (free) + Branding section (Pro only)

Add any dividend-paying stock, REIT, ETF, closed-end fund, or investment trust here. Click ＋ Add Counter to enter a holding manually, or Import Holdings to bring in multiple at once from a spreadsheet.

Screenshot: The Add Counter form, Pro version (extra fields highlighted)

Dividend Counter Form Fields

Importing Holdings from a Spreadsheet

Click Import Holdings to add many holdings at once. The importer accepts two kinds of file, and you can start with the simpler one. A simple summary has one row per holding. A richer history has several rows for the same ticker, one for each dividend event, so that Income Refinery can also see the dividend trend and work out how often, and in which months, each holding pays.

The minimum is a ticker and a number of units. Each holding needs a Ticker (or Symbol) and Units (or Shares, or Quantity) on at least one of its rows. You do not need nine columns. A file with only Ticker and Units is accepted, and so is a file that adds a DPU, a Frequency, or an Ex-Date and a Payment Date.

Several rows for one ticker. Repeat the ticker on every dividend event. At least one of the rows must have Units. Repeating the same Units on every row is recommended, especially for a spreadsheet made by an AI assistant. Rows are grouped by ticker, so ten rows for the same ticker become one holding.

Ex-Date and Payment Date. The Ex-Date identifies the dividend event and puts the events in order, so the newest event sets the DPU. The Payment Date is when the cash is expected or was paid, and it is preferred when working out which month the cash arrives in. When a row has both, they are kept separately: an Ex-Date of 28 March with a Payment Date of 15 April is a March event whose cash arrives in April. A row that has only a Payment Date is still a dated event, and the Payment Date puts it in order. Only a row with neither date is read as the holding's own current DPU rather than as a dividend event.

File types and capacity. Import Holdings reads XLSX, XLS, XLSM, CSV and TSV files up to 20 MB. On the free plan the finished portfolio can hold up to 10 holdings. Holdings are counted after the rows have been grouped by ticker, and an update to a holding you already have does not take a new slot. Several history rows for one ticker are one holding and use one slot, so twenty rows for a single ticker do not use twenty slots.

How the DPU and the Payment Schedule Are Worked Out

The DPU is the latest payment, not an average. Income Refinery takes the most recent known cash payment per share or unit as the DPU and uses it as a forward run-rate. Annual income for a holding is Units × current DPU × payments per year, then adjusted for withholding tax and currency conversion as set up in Settings. This is a planning assumption, not a prediction of what the issuer will pay. If a payout changes, update the DPU.

Earlier payments are kept separately as history. When a Lookup or an import supplies several dated payments, the newest sets the DPU, and the earlier ones feed the Pro Dividend Health Panel and the payment pattern. An average of past payments is never used as the forward DPU. For example, if the last four payments were 0.20, 0.25, 0.25 and 0.25 (newest first), the DPU is 0.20, the earlier average is 0.25, the Dividend Health Panel shows a Potential cut of 20%, and a quarterly holding earns 0.80 per unit a year.

Frequency says how often a holding pays. Payment Months says when. They are different facts. A Frequency of Quarterly gives four payments a year, and that count is what annual income uses, but it does not prove that the payments fall in March, June, September and December. Payments per year and payment months come from the first of these that applies:

Once saved, a holding whose months are estimated, approximate or assumed keeps that note. The holding shows (estimated), (approx.) or (assumed) beside its payment months. In Pro, the Excel Holdings sheet has a Schedule Basis column and a Data Quality warning for the same holdings, and the calendar carries a note that actual cash timing may differ. Annual income is not changed by any of this, because it already uses the expected number of payments a year.

Lookup. Lookup uses the newest payment as the DPU. The payment dates support the schedule only when they are enough to confirm it. Lookup does not always know the schedule: when it finds a DPU but cannot confirm the schedule, it reports a Partial match and leaves the Frequency for you to choose before you can save a new holding. Always check the Frequency and months before saving.

Quick Search Pro. The Add by ticker bar shows a result as Verified when both the DPU and the schedule are confirmed, and one-click Add is available. When the DPU is found but the schedule is not, the result shows as Partial with the note Payment schedule could not be confirmed, no annual estimate is shown, and one-click Add is switched off. Quick Search never assumes Quarterly. Choose Customise & add, set the payment frequency, then save.

Import Holdings and the Watchlist. The priority list above applies to both. A DPU on a row with neither an Ex-Date nor a Payment Date is the holding's current DPU; otherwise the newest dated event supplies it (by Ex-Date, or by Payment Date when the row has no Ex-Date), and the older events supply the trend. A written 0 is kept as a real zero and a blank is kept as unknown. The preview marks from pay dates (real Payment Dates), estimated (from Ex-Dates), approximate (from the Frequency only), assumed (Quarterly fallback) and kept (the holding's existing schedule), so you can see every assumption before you confirm.

Excel export Pro. The Holdings sheet exports the same current DPU, payments per year and payment months you see in the app, with a Schedule Basis column beside the months, and the annual income on the Summary and Calendar sheets matches the dashboard.

Search, Sort & the ≡ Table View

Once holdings are added, a search and sort toolbar appears above the list. Type any part of a name or ticker to filter instantly, and use the sort dropdown to order by income, DPU, name, or units held.

Supported Stock Exchanges: 30 Global Markets

The Add Holding dropdown lists all 30 exchanges below, and choosing one sets the currency for you. Twenty-seven of them trade in a currency with a live rate. Three, Tadawul (SAR), TWSE (TWD) and MOEX (RUB), have no live rate: for those, the form asks you to type the exchange rate yourself, and the holding is not counted until you do. London prices are quoted in pence (GBp), which Lookup does not apply; for a London holding, enter the DPU in pounds and keep the currency as GBP. The same applies to any security quoted in cents or another sub-unit.

Click ＋ Add Property to track net rental income from any property in any currency. FX conversion to your base currency is handled automatically.

This section handles everything that isn't a stock or a property. Choose from 12 categories, then fill in the amount, currency, and payment schedule. The Capital Deployed field Pro lets you record the capital behind each stream so the app can calculate your yield on that capital.

Amount is the income you receive per payment event, not the annual total. The app calculates your annual figure by multiplying by the number of payments per year, so a bond paying $500 each June and December is entered as $500 Semi-annual, not $1,000 Annual. This is the same convention as the DPU field in Holdings.

Moving from Free to Pro

Free and Pro use the same data format, so your portfolio comes with you. Your holdings, properties, other income, currencies, exchange rates, payment months, targets and withholding setting all carry over, with their record IDs. Nothing is removed, and nothing is filled in for you: cost basis and market prices are Pro fields that Free does not have, so they start empty until you add them.

Both versions include a Share your progress button in the hero panel (Pro: on the Income Sources tab), just below your monthly income total. Clicking it opens the Share Your Progress modal, which generates a branded PNG image of your income dashboard that you can download or post directly to social media.

A snapshot is a point-in-time record of your monthly income and portfolio value. Captured once a month, they build a historical record of your progress toward financial independence, and power the Income Over Time chart. Without snapshots the History chart has nothing to plot, so capturing your first one is worth doing on day one.

Click Capture Snapshot in Settings → Portfolio Snapshots to open the snapshot form. The app auto-fills monthly income and portfolio value from your current data; you can edit either field before saving.

The Income Over Time chart is a full-screen view that plots your portfolio snapshot history as a line chart: your passive income journey in one glance. It requires at least one saved snapshot to display data; two or more reveal the trend line.

The Forecast & Projection engine is Income Refinery Pro's answer to the most important question in passive income investing: "When will I reach financial independence?" It takes your current income as the baseline and projects it forward simultaneously under three scenario bands: Conservative (the floor), Base (your own assumptions), and Optimistic (the ceiling), giving you a realistic range rather than a single optimistic line. Open it via Analyse ▾ → Forecast; it appears as an inline collapsible panel directly on the main dashboard.

Click Show assumptions to expand the inputs panel. Your settings are saved between sessions.

Forecast & Projection Assumptions

Financial Independence Tiers (Lean, Standard & Fat FI)

Within the assumptions panel, you can set the percentage thresholds for each FI tier; these feed directly into the FI Milestones strip on the Income Sources tab and the projected FI date in the Target Drawer. The defaults match most FIRE community conventions but are fully adjustable.

The What-If drawer is Income Refinery Pro's scenario planning tool: a side drawer that lets you model hypothetical changes to your portfolio before committing real capital. It has three interconnected parts: a Hypothetical Portfolio builder, two focused scenario cards (Capital Deployment and Distribution Change), and a live Scenario Calendar that shows the combined 12-month income impact visually. Open it via Analyse ▾ → What-If.

Hypothetical Portfolio Builder

The top section of the drawer lets you add fictional income sources to model "what if I bought this?" without touching your real portfolio. Nothing added here affects your actual data.

Each item you add appears in the list below the form buttons. The Scenario Calendar updates immediately to show how the hypothetical income stacks up against your actual portfolio month by month. Remove any item with its × button.

Capital Deployment & Distribution Change Scenarios

Two cards sit below the Hypothetical Portfolio, each modelling a different type of change to your portfolio:

Scenario Calendar: 12-Month Income View

The Scenario Calendar at the bottom of the drawer is the most useful part for day-to-day planning. It renders a 12-month calendar showing your modelled total income per month: your real holdings plus all the hypothetical items you've added. Months with no income are highlighted. Use it to check for seasonal gaps before committing to a new position.

The FI Milestones strip appears automatically between the hero and the monthly calendar on the Income Sources tab. It shows three financially independent income levels, calculated from your monthly target, and tells you how far away each one is, updated in real time every time you add or edit a holding.

The milestone percentages (70% for Lean, 150% for Fat) are configurable in the Forecast panel's assumptions section. Projected dates are driven by your Forecast assumptions, so they update as you adjust your monthly capital contributions and expected yield.

If you hold many positions, entering them one by one can be tedious. Use these ready-made prompts with your favourite LLM, tested on Claude and Gemini. Prompt 1 is all you need to get started: it generates one row per dividend event (with units, and with ex-dates and payment dates where they can be verified) which the importer uses to bulk-add your holdings and populate the Pro Dividend Health Panel in a single operation. Prompt 2 is optional: use it if you want a dedicated Priority 1 Watchlist to power the Lookup button with a fast, offline cache. In Pro, the welcome screen links straight to this section.

Prompt 1: Holdings Import (one row per event → Import Holdings + DPU trend)

Generates one row per dividend payment event per holding, with units on every row. Use this with the Import Holdings button in the Holdings section. The importer automatically groups rows by ticker (one counter is created per holding) and collects the dated events to populate the Pro Dividend Health Panel and DPU trend. No separate watchlist upload is needed. The prompt asks for about 24 months of real events per ticker, which is enough for the importer to confirm how often each holding pays even when a payment is missing. The newest event becomes the DPU, and the Dividend Health Panel looks at the newest eight. The optional columns are not mandatory: a field the assistant cannot verify should be left blank. Verify dividend amounts, currencies, dates and payment schedules against issuer, fund or broker records before importing.

For the simplest import, Ticker and Units are enough to start. The prompt below asks an AI assistant for a richer version with dividend history, Ex-Dates and Payment Dates where they can be verified. Optional fields should be left blank rather than guessed.

Name the dividend column DPU. The importer reads a column called DPU, DPS, Dividend Per Share or Distribution Per Unit as a per-unit figure. A column called Amount, Dividend, Distribution or Payout might hold the total cash you received, so it is not read as DPU: the preview says so, and the DPU stays blank until you enter it. A DPU of 0 is kept as a real zero; a blank is kept as unknown.

You do not need two years of history. Ticker and Units are enough. DPU, Frequency, Payment Months, Ex-Date and Payment Date give Income Refinery better information, but leaving a field blank is safer than guessing. More spreadsheet rows do not mean more holdings. Ten historical rows for the same ticker are grouped into one holding.

Prompt 2: Watchlist Pro (one row per event → Priority 1 Watchlist)

Generates one row per dividend payment event per holding, without units. Upload this in Settings → Dividend Lookup Sources → Priority 1 Watchlist so the Lookup button resolves any ticker instantly from your own file: offline, no rate limits, no API key needed. It also feeds the Dividend Health Panel when you run Lookup on an existing counter. For initial dashboard setup, Prompt 1 covers both import and DPU trend in one step; Prompt 2 is most useful for keeping the Lookup cache fresh as you add new tickers over time. Ex-Date must be filled on every row: rows without one are excluded from trend analysis. Lookup matches the ticker exactly as written, so keep the exchange suffix in the file (for example D05.SI). A plain symbol is matched to a suffixed one only when that is unambiguous and the currencies agree. If your file holds the same symbol on two exchanges, such as ABC.SI and ABC.L, a lookup for ABC.SI uses only the ABC.SI rows, and a lookup for plain ABC finds nothing in the file.

API keys are entered directly in Settings → Dividend Lookup Sources. Paste a key in the relevant field, click Save Settings, and the Lookup button uses it automatically from that point on. All keys are stored locally on your device, never sent anywhere except directly to the API provider when you do a Lookup. JSON backups leave your keys out unless you tick Include API keys in backup, and importing a backup without keys keeps the keys already on your device.

Love Income Refinery? Share it with a friend and you can both come out ahead: they get a bigger discount on Pro, and you earn a referral reward for every friend who joins. It costs nothing to set up and takes about a minute.

Two ways to share

Setting up your own code