Amounts & Balances

The Lunch Money API uses four properties — amount, balance, currency, and to_base — consistently across all objects that deal with money. Understanding how they work will help you build accurate, multi-currency-aware integrations.

`amount`

amount is a string representation of a monetary value, precise to up to four decimal places. It appears on transactions, child transactions, recurring items, budget objects, and rollover pool adjustments.

"amount": "12.5000"

amount is always expressed in the currency specified by the companion currency property on the same object. Amounts are never rounded or converted.

`balance`

balance is a string representation of an account's running balance, also precise to up to four decimal places. It appears on manual accounts, Plaid accounts, crypto accounts, and balance history entries.

"balance": "1500.0000"

Like amount, balance is always in the currency of the same object and follows the same sign convention.

`currency`

currency is an ISO 4217 currency code (e.g., "usd", "eur", "gbp"). It is present on every object that carries an amount or balance and tells you what currency those values are in. See the Supported Currencies guide for the full list.

`to_base`

to_base is a floating-point number that represents the amount or balance converted to the user's primary currency. It is present on transactions, account objects, balance history entries, budget objects, and summary responses.

"amount": "12.5000",
"currency": "eur",
"to_base": 13.62

to_base is calculated by the API at response time and is read-only — it is never accepted on POST or PUT requests.

to_base is the recommended property to use when you need to:

Display amounts and balances in a single consistent currency across a multi-currency account
Perform arithmetic across transactions or accounts in different currencies

Sign Convention

The Lunch Money API always uses the following sign convention for amount, balance, and to_base:

Value	Meaning
Positive	Money going out — debits, expenses, liabilities
Negative	Money coming in — credits, income, assets with negative balance

This is standard accounting convention (the bank ledger perspective). For example:

A $50 coffee purchase has "amount": "50.0000"
A $1,200 paycheck deposit has "amount": "-1200.0000"
A savings account with a $5,000 balance has "balance": "5000.0000"

App Display Setting

The Lunch Money app has a setting — "Show Debits as Negative, Credits as Positive" — that can flip how amounts are displayed in the UI. This setting is exposed in the API as debits_as_negative on the User object. It has no effect on the API. The API always returns positive values for debits and negative values for credits regardless of this setting. Apps may read debits_as_negative to match the user's preferred display format when showing amounts in their own UI.

Exception: Budget and Summary Amounts

Budget objects and summary response objects are an exception to the sign convention above. The amount and to_base values on these objects represent aggregated totals rather than directional flows, and are always returned as positive magnitudes.

If you are reading amount or to_base from a budget or summary object, do not apply the debit/credit sign interpretation described above — treat the values as positive totals.