Accounts¶

If you take a typical transaction, money moves between two parties. In ledger, you call them Account. At least two accounts are involved in any transaction. Accounts are also hierarchical. This helps with the organization. For example you can treat EPF and PPF as two accounts namely Assets:Debt:EPF and Assets:Debt:PPF. The hierarchy helps you ask questions like what is the balance of Assets:Debt, which will include both EPF and PPF.

Even though ledger doesn't have any strict Account naming convention, Paisa expects you to follow the standard naming convention.

There are five types of account namely

Assets
Liabilities
Income
Expenses
Equity

All the accounts you create should be under one of these accounts. This naming convention is a necessity, because without which, it's not possible to tell whether you are spending money or investing money. A transaction from Assets account to Expenses account implies that you are spending money.

Money typically flows from Income to Assets, from Assets to either Expenses, Liabilities or other Assets, from Liabilities to Expenses.

graph LR
  I[Income] --> A[Assets];
  A --> E[Expenses];
  A --> A;
  A --> L[Liabilities];
  L --> E[Expenses];

As a general principle, try not to create too many accounts at second level. The UI works best when you create less than or equal to 12 second level accounts under each type. For example, you can have 12 accounts under Expenses. But if you want more, try to add them under 3^rd level, example Expenses:Food:Subway.

Assets¶

All your assets should go under Assets:. The level of granularity is up to you. The recommended convention is to use Assets:{instrument_type}:{instrument_name}. The instrument type may be Cash, Equity, Debt, etc. The instrument name may be the name of the fund, stock, etc

Checking¶

Assets:Checking is a special account where you keep your money for daily use. This will be included in your net worth, but will not be treated as an investment. So gain page for example, will exclude this account and won't show the returns. If you have multiple checking accounts, you can use sub accounts as well, for example Assets:Checking:HDFC and Assets:Checking:AXIS.

The distinction is necessary because Checking account is an asset, but not an investment. So you ideally you want to disregard them when you calculate your absolute returns etc.

Income¶

All your income should come from Income:. The typical way is to treat each employer as a separate account like Income:Salary:{company}

Interest¶

Income:Interest is a special type of account from the perspective of returns calculation. Let's assume you have bought APPLE stock. You might be buying them at regular intervals. To calculate your returns, we can compute the difference between purchase price and current price.

Now in case of FD, you will get your interest credited to your account. The returns is the difference between the amount you deposited and the final balance. It's essential we need to know which transactions are deposits and which are interest credits.

Any money that comes from the sub account of Income:Interest will be treated as interest. This convention allows paisa to calculate the returns of any debt instrument without explicitly specifying anything else.

Income:Interest:{name} - interest debit account

Capital Gains¶

2018/03/01 Withdrawal
    Assets:Checking                  6775.49 INR
    Income:CapitalGains:Equity:NIFTY  -22.68 INR
    Assets:Equity:NIFTY               -100 NIFTY {67.5281 INR} [2018/01/01] @ 67.7549 INR

Let's say you have an asset account named Assets:{name} and you make some profit when you sell the asset, this profit should come from capital gains account named Income:CapitalGains:{name}.

Expenses¶

All your expenses should go to Expenses:{category} accounts. You can also have more than 2 levels as well. The expense page will roll it up to 2 level wherever necessary.

Tax¶

Income tax paid to government should be credited to Expenses:Tax account. This is used to calculate your Net Income and your Savings Rate. If you want to track different types of taxes, you can use sub accounts as well, for example Expenses:Tax:Income and Expenses:Tax:GST.

Liabilities¶

Credit Card¶

Credit card accounts should be named Liabilities:CreditCard:{name}, for example Liabilities:CreditCard:Freedom and Liabilities:CreditCard:AmazonPay

Equity¶

Equity is used in rare cases where you want to balance the transaction, but none of the other accounts are suitable for the purpose. Let's say you have 1000 INR in your real bank account and you want your checking account in Paisa to have same balance, you can use Equity account to balance the transaction.

2022/01/01 Opening Balance
    Assets:Checking:SBI       1000 INR
    Equity:OpeningBalance

Icons¶

Each account is associated with an icon and is shown along with the account name in most places. Paisa assigns icon based on few simple rules and it usually falls back to a generic icon. To modify the icon, go to the configuration page, add a new Account and specify the name of your account and then select icon of your choice. Paisa ships with four icon sets.

Experimental

There is a wide range of free icons available, but adding each icon set to Paisa would increase the app binary size. So a balance has to be struck between the number of icons and the app size. Feel free to start a discussion if you feel strongly about any icon set. The current icon sets are not final, they may be replaced if a better alternative is found.

Account Notes¶

You can attach a free-text note to any account (for example "Emergency fund", "Company 401k") without editing the ledger file. Notes are stored in Paisa's database and do not affect journal parsing.

Navigate to Accounts → [account name] to open the account overview page, which contains a textarea for composing or editing a note, plus a Delete button to remove it.
On the Accounts → [account name] → Transactions page, an existing note is shown inline in the page header as a highlighted tag. A Notes button next to the tag takes you directly to the notes editor.

Notes are persisted immediately via the API when you save them.

Account-Level Transaction History¶

Click on any account balance widget on the dashboard or on an account row in the Assets or Accounts list to open a filtered transaction history for that specific account. The route /accounts/[name]/transactions shows all transactions that touch the selected account (or any sub-account below it).

Account Reconciliation¶

Note

Reconciliation is disabled by default. Enable it by setting enable_reconciliation: true in paisa.yaml.

When reconciliation is enabled, Paisa tracks the last date each account was reconciled and how frequently it should be reconciled.

Reconciliation Status Badge¶

A color-coded badge appears next to every account balance row and on the account detail page:

Green – reconciled within the expected frequency window.
Amber – overdue (more days have elapsed than the configured frequency_days).

Clicking a badge opens an in-page modal where you can update the reconciliation date without navigating away, preserving page state on the Dashboard, Assets, and Account detail pages.

When reconciliation is enabled, the dashboard shows an Account Reconciliation widget with:

Counts of up-to-date and overdue accounts.
Quick links to reconcile overdue accounts.

Reconciliation API¶

Method	Endpoint	Description
`GET`	`/api/accounts/reconciliation`	List reconciliation metadata for all accounts.
`GET`	`/api/accounts/:account/reconciliation`	Fetch metadata for a single account.
`PATCH`	`/api/accounts/:account/reconciliation`	Update `last_reconciled_date` and `frequency_days`.

Responses include computed days_since (days since the last reconciliation) and is_overdue fields.