Reading amounts

Amounts in the Light API follow four rules. Each is simple on its own; the mistakes come from mixing them up, so this page states each one and where it applies.

# 1. Amounts are integers in minor units

1250 with currency: "USD" is 12.50 USD. 150 with currency: "JPY" is 150 yen, because the yen has no minor unit. There are no decimals on the wire, so nothing is lost to floating-point rounding.

Fields whose name ends in InMajors are the exception: they carry the same figure as a decimal (12.5) and appear beside the minor-unit field on responses. Where a request field is named InMajors, it takes majors; everything else takes minor units. MCP tools are different again: there, every amount is in major units. See Using Light from an AI client.

# 2. Direction is separate from size

Ledger amounts are never negative. Each carries a size and a direction, and the direction lives in dcSign: D for debit, C for credit. A journal entry line is sent as:

{ "netTransactionAmount": { "amount": 125000, "dcSign": "D" } }

A negative amount is rejected (ACCOUNTING_DOCUMENT_LINE_NEGATIVE_AMOUNT). One dcSign covers all three currency amounts on a ledger line: a line is a debit or a credit as a whole.

Document endpoints hide this for the common case. On a bill, a positive line amount is an expense debit; on a sales invoice, a positive line amount is a revenue credit. You only state dcSign yourself on journal entries and bank transactions.

# 3. Signed figures exist, and their polarity depends on the endpoint

For convenience, List ledger transaction lines also returns each amount as a signed number: signedTransactionAmount, signedLocalAmount, signedGroupAmount. On those, a credit is positive and a debit is negative. Summing signedLocalAmount over an account therefore gives a credit-positive balance: a revenue account sums positive, an expense account sums negative.

General ledger summary and the bank account balance endpoint return balances with the opposite polarity: debit-positive, the way a trial balance is usually read, so a bank account in overdraft is negative there.

Reconciling one against the other means flipping the sign on one side. If you keep one rule, keep this one: dcSign plus the unsigned amount is always unambiguous. Read the sign of a signed field only after checking which endpoint you are on.

# 4. Every ledger line carries three currencies

Light keeps every ledger line in up to three currencies at once, and the API returns all three:

Local and group amounts are computed at posting, from the exchange rate on the document's valuationDate (which defaults to the posting date), and then stored. A report in group currency reads stored figures; it does not re-convert at report time. If a document supplies its own rate (localCurrencyFxRateOverride, groupCurrencyFxRateOverride), or a journal entry states local and group amounts directly, those are used instead.

Which one to read:

• Transaction: what the document says, in the currency it was issued in. Use it to match against an invoice or a bank statement line.
• Local: the entity's statutory books. Use it for anything filed in that entity's country.
• Group: consolidation. Use it to add up across entities.

Because each line converts separately, the local or group totals of a transaction can end up a few minor units off zero after rounding. Light adds a rounding line on its rounding account so that debits equal credits in every currency. That line has no transaction amount, and it is not an error.

# Where the rules bite

• A bill for 1,000.00 is amount: 100000. Sending 1000 creates a bill for 10.00.
• Totals on the accounting documents list are absolute values; ignore the dcSign on totalTransactionAmount there.
• Zero-amount lines count as debits internally. Do not read direction off a zero.
• A journal entry that states local and group amounts directly must balance in those currencies too, and cannot combine them with tax on the same lines.

Next: Document lifecycle.