How Light records money

Every number Light reports comes from one place: 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 explains the three objects involved and the one rule that ties them together.

# Documents are what you edit

A bill, a sales invoice, a journal entry or a card transaction is an accounting document: the editable record of a business event. Who it involves, what it is for, how much, in which currency, 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 also opens 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. It is a plan.

# Posting turns a document into a ledger transaction

Posting is the moment a document becomes 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. That is what makes the ledger auditable: the history of a mistake is as visible as the mistake.

List ledger transaction lines is the ledger itself. Every report Light produces is a sum over these lines, so if you want to rebuild a figure, this is where to start.

# Why every transaction has two sides

Money never appears or disappears; it moves. 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 always answer two questions at once: 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.

This is why the API 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 do not need to hold this in your head to use the API, but it explains what you will see on a ledger line. 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 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 only records that they belong together, which is what open-item and ageing reports rely on. If the exchange rate moved between invoice and payment, the difference is posted as a separate realised FX transaction.

# What this means when you call the API

• 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 is accounting until it is posted.
• Reversals leave two sets of lines that net to zero. When you sum ledger lines for a period, that is correct, not a duplicate.
• You cannot post an unbalanced entry, and you cannot post a line without a counterpart. If a request fails on balance, the request is describing half an event.

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