How Light records money

Every number Light reports is a sum over the ledger. Everything else in the API (bills, sales invoices, journal entries, card transactions) is a way of getting a balanced entry into it. This page covers the three objects involved and the rule they all follow.

# Documents

A bill, a sales invoice, a journal entry or a card transaction is an accounting document: the editable record of a business event. It records who the event involves, what it is for, how much, in which currency and on which date. Documents have lines, and each line points at a ledger account and carries an amount.

Every document has a documentType, a two-letter code that is also the first segment of its document number:

List accounting documents returns all of them in one shape. Each type also has its own endpoints for creating it and moving it through its life.

A document in DRAFT has no effect on any report.

# Posting

Posting is what turns a document into accounting. Light validates the document, assigns its document number (documentSequenceId, for example AP/001/000000042), converts every amount into the entity's local currency and the company's group currency, adds the lines the document implies but does not show (tax, the balancing line, rounding), and writes the result as a ledger transaction: a set of ledger transaction lines that share one transaction number (TX/…).

Ledger lines are never edited or deleted. If a posted document is wrong, Light posts a reversal: a new transaction with the same lines and the directions flipped. The document goes back to draft or is archived, keeps its number, and both the original and the reversing lines stay in the ledger. The ledger therefore carries the correction next to what it corrected, which is what makes it auditable.

List ledger transaction lines returns the ledger itself. Every report Light produces is a sum over these lines, so start there to rebuild a figure.

# Why every transaction has two sides

Every business event changes two things at once. When a company buys software for 100, it owes 100 more to a vendor and has 100 more expense. When a customer pays, the bank balance goes up and the amount the customer owes goes down. A ledger transaction records both halves, so the books show what changed and what it was balanced against.

The two halves are called debit and credit, and each ledger line carries one of them in dcSign (D or C). Within every ledger transaction, debits equal credits, in every currency the line carries. Light enforces this when it posts: a journal entry whose lines do not net to zero fails with ACCOUNTING_DOCUMENT_LINES_DEBITS_AND_CREDITS_NOT_ZERO_SUM, and one with only debits or only credits fails with ACCOUNTING_DOCUMENT_LINES_NO_CREDIT_AND_DEBIT.

The API therefore never lets you write a single ledger line. You describe an event as a document, and Light produces the balanced transaction, adding the other side where the document type implies it:

• On a bill, you enter expense lines; Light adds the balancing line on the entity's accounts payable account.
• On a sales invoice, you enter revenue lines; Light adds the balancing line on accounts receivable.
• On a journal entry, you state both sides yourself, line by line, with an explicit dcSign on each amount.

Whether a debit makes a balance go up or down depends on the kind of account: debits increase assets and expenses, credits increase liabilities, equity and revenue. You can use the API without memorising that, but it explains what a ledger line looks like. The expense line of a bill is a debit and its accounts payable line is a credit; a customer payment debits the bank and credits accounts receivable.

# Settlement: clearing

A posted bill is money owed. When the payment posts, the two documents settle each other on the accounts payable account. Light records that as a clearing event, and the bill's status moves to PARTIALLY_CLEARED or CLEARED. Clearing does not rewrite ledger lines: the payable line and the payment line already net to zero. It records only that they belong together, which is what open-item and ageing reports read. If the exchange rate moved between invoice and payment, the difference is posted as a separate realised FX transaction.

# What this means for your calls

• Read the ledger from ledger transaction lines, and documents from their own endpoints or the accounting documents list. A ledger line points back at its document through accountingDocumentId.
• A draft is invisible to reports: nothing you send reaches the ledger until it is posted.
• Reversals leave two sets of lines that net to zero. Summing ledger lines for a period includes both, which is correct rather than a double count.
• You cannot post an unbalanced entry, and you cannot post a line without a counterpart. A request rejected on balance is missing one side of the event.

Next: Reading amounts, which covers how the amounts on those lines are expressed.