Books

Books is the double-entry ledger behind every money module. Costs, vault movements, invoices, bills and shop orders post here, and the books turn them into profit and loss, a trial balance and profit per order. The sidebar calls it Books; the module is ledger.

In the sidebar under Money → Books. Handles money: when an agent tries to change anything here, a person is asked to approve it first (Agents and approvals).

Choose an entity at the top: the figures, the orders and the month locks are all about that entity's books. Entries are not typed in on this screen. They arrive from the modules that own the money, and a posting the books refuse is listed rather than guessed into an account. Every field has an (i) that says what it is for, and the app's quick search opens a tab of this page directly.

How the books work

• Double entry. Every entry has lines that debit and credit accounts, and debits equal credits in each currency. An entry that does not balance is refused.
• Entities. Each business whose books are kept here is an entity, such as "Acme Ltd". An entity has a functional currency, which never changes, and its own chart of accounts. One entity can be the default: anything not linked to a particular entity books there.
• Chart of accounts. A new entity starts with a default chart. Accounts have a code, a type and sometimes a role, such as suspense or the fallback for money somebody paid personally.
• Postings from other modules. A module offers a posting under its own name and a key for the thing it describes, such as one cost or one movement. Offering the same thing again changes nothing if it has not changed. If it has, the old entry is reversed and a new revision written, so every correction is visible.
• Multi-currency. Each line keeps its own currency and is converted into the entity's functional currency at the rate on or before the day it was booked. Rates come from Accounts, which records official rates for every day the books need. Once a rate has been used, it is frozen. Currency codes may be longer than three letters, so crypto such as USDT can be held.
• Review. An entry booked to suspense or to a fallback account is flagged for a person. They reclassify it to the right accounts, or mark it reviewed.
• Refusals. A posting that cannot be booked is refused with a code and kept on a list until its module posts it. Common codes are NO_RATE (no exchange rate for the day), UNKNOWN_ACCOUNT (the chart lacks an account the posting needs), PERIOD_LOCKED (the month is locked) and NO_ENTITY or ENTITY_UNMAPPED (nobody said whose books it goes to). Each module's hourly catch-up job offers its refused postings again.
• Parked postings. A posting refused three times in a row for the same reason, where it is known what would unblock it (a rate or an entity link), is parked. It is still tried every hour and posts on the first run after the rate or link appears, but the repeats no longer count as news.
• Periods. A month of an entity can be locked. Nothing dated in it can then be booked, reversed or reclassified. A month cannot be locked while an entry in it awaits review.
• Reconciliation. A bank or provider statement is imported for one account and period, then compared with the lines on that account. Reconciliation only proposes matches and differences. A person decides each one; deciding books nothing.

For how rates are found and what to do about postings that are stuck, see Exchange rates and stuck entries.

What you see

Across the top: how many entities keep books, how many entries await review, how many postings were refused, and whether exchange rates are available. Below are four tabs.

Statements

Choose an Entity, a From and To date, and a currency to Consolidate in.

• Profit and loss, per entity: as it was earned and spent, and again in the entity's functional currency.
• Trial balance: every account's balance up to the To day.
• Profit and loss, consolidated: all entities translated into one currency, with The rates it used and any Days it could not translate.

Orders

What each shop order earned, what costs were attributed to it, and what is left over, read from the books. Tick orders and choose Add a cost to put a cost against them, optionally saying it was already paid from a vault. The cost is recorded as a bill in Bills and posted under each order's own key.

Books and shops

• Each entity, its currency and which shops and suppliers book to it. New entity starts books for another business.
• Link a shop or a supplier to an entity. A shop with no books has every order refused rather than guessed into a company's accounts. After linking, re-post the shop's past days so the refused orders are booked. Vaults, costs and projects need no link: they go to the default entity.
• Add missing accounts on an entity adds any accounts the default chart has gained since the entity was made.
• Month locks: lock a month for the chosen entity, or unlock one with a reason. The reason is kept.

What happened

• What synced: each shop's newest sync run and what it posted.
• Reconciliation: each run and its proposals (match, amount differs, missing in the books, missing in the statement) with the evidence. Decide each one with a note. When nothing has been issued or imported yet, it says there is nothing to check.
• Waiting: refused postings grouped by what they wait on (a missing rate, an unlinked shop or source, or a refusal code), with how many there are, from which day, and how many are parked. With none it says "Nothing is waiting."
• What nobody has answered: every refused posting, with the module it came from, the refusal code, why, what it was for, how many tries, when it was last tried, and whether it is parked.

What you can do

Start books for a business

1. Open Books and shops and choose New entity.
2. Give it a name, its functional currency and its kind (company, shop, service or other). The currency cannot change later.
3. Optionally make it the default entity, so vaults, costs and projects book to it.
4. Link each shop and supplier whose money belongs to it.

Clear a refused posting

1. Open What happened and read Waiting and What nobody has answered.
2. Fix the cause: record the missing rate in Accounts for NO_RATE, choose Add missing accounts for UNKNOWN_ACCOUNT, link the source to an entity for ENTITY_UNMAPPED, or unlock the month for PERIOD_LOCKED.
3. Wait for the source module's hourly catch-up, or re-post from that module. The row leaves the list once the posting is booked.

Review and reclassify flagged entries

Flagged entries are reviewed through the API or by an agent. Reclassify moves the money from suspense or a fallback account to the accounts it belongs on. Mark reviewed clears the flag once a person has checked the entry, and is refused while money still sits in suspense. A source map says which account a vault, money source or other source object books to from now on, so later postings arrive already classified.

Book or reverse an entry by hand

A manual entry, with lines that balance in each currency, is posted through the API or by an agent with ledger:post. Reversing writes a new, mirrored entry; nothing is deleted. Reversing a reclassification undoes it.

Reconcile a statement

1. Import the statement for one account and period through the API or an agent, or from a statement reading in Extraction. It records what the statement said and books nothing.
2. Run reconciliation. It writes proposals, never entries.
3. In What happened → Reconciliation, decide each proposal. Confirm records that the two sides agree. Where money is missing from the books, book it first, then name that entry when you confirm.

Lock a month

1. Open Books and shops, choose the entity, then the month under Month locks.
2. Lock it. Everything in it must be reviewed first.
3. To reopen it, unlock it and give a reason.

See what each order made

Use the Orders tab, or ask for the profit report through the API. The report can be downloaded as a spreadsheet or CSV, whose totals are live formulas. Orders marked as tests are left out. An order missing a cost reports its profit as unknown, not as a figure. Costs for many orders can be loaded at once from the exported CSV with its cost columns filled in.

Who can do what

Permission	Label	Lets you
ledger:read	See the books: entries, trial balance, P&L	Open Books, every report, the refusals and the maps. Agents need it for the read tools.
ledger:post	Book, reverse, review or reclassify an entry by hand	Post manual entries, reverse, mark reviewed, reclassify, load order costs and move shop entries to their order's key.
ledger:manage	Set up entities, accounts and mappings	Create and change entities and accounts, link sources to entities, map source objects to accounts, and add missing accounts.
ledger:lock	Lock and unlock periods	Lock a month, and unlock it with a reason.
ledger:reconcile	Run reconciliation and decide its proposals	Import statements, run reconciliation and decide proposals.

Postings from other modules do not need ledger:post: the cost, movement or invoice behind them was already allowed by its own module's permission. Roles and how permissions are granted are explained in People, roles and permissions.

What runs on its own

Job	When	What it does
waiting-alerts	Every day at 09:00 UTC	Groups the refused postings each workspace still has by cause (a missing currency rate, an unlinked source, or a refusal code) and tells the workspace admins once per cause, in plain words: how many, from when, and what would unblock them. A cause is told again only after a day, and only if more postings wait on it than last time. A cause nothing waits on any more is forgotten, so it is told afresh if it comes back. Rate notices from Accounts (a rate held for checking, a currency with no source, a late rate) go out the same way.

The books themselves are filled by the modules that post to them, each of which has its own hourly catch-up job: Costs, Vaults, Invoices, Bills and Shops.

Needs

Nothing else must be switched on. The books are only as full as the money modules that post to them, and need exchange rates from Accounts for anything not in an entity's own currency.

Who posts here and what it reads

• Post entries: Costs (each cost that is not personal), Vaults (each movement that is not a cost's own), Invoices (issued invoices, corrections and credit notes), Bills (issued bills, payments and claims) and Shops (orders and refunds, through their ledger sync).
• Read from others: exchange rates from Accounts, and order details and sync runs from Shops, for the profit and order reports.
• Read by others: Invoices and Bills read what the books hold for their own keys when they reconcile, and Costs and Vaults compare their records with the books when they catch up.

For agents

An agent can read every report, set up entities, accounts and maps, book and correct entries, lock months, and run reconciliation.

This module handles money. When an agent calls a tool here that changes something, the call goes to a person for approval first, whatever the agent's policy says, and no per-tool rule can set it to allow. Reads follow the agent's policy as usual. A person working in the app, or an API key somebody set up, is not held by this rule: their permissions decide. Tools marked spends or destructive below can never be allowed without asking.

Read and report (read only)

• ledger.entities: the entities whose books are kept here.
• ledger.accounts: the chart of accounts, for one entity or all.
• ledger.entries: journal entries, newest day first, 50 at a time.
• ledger.entry: one entry with its lines, rates and review state.
• ledger.trialBalance: the trial balance of one entity up to a day, or consolidated into a reporting currency.
• ledger.profitAndLoss: profit and loss of one entity, or consolidated with every rate used.
• ledger.profit: what each order made, with by-store and by-month summaries.
• ledger.rejections: postings the books refused, and why.
• ledger.maps: which account each source object books to.
• ledger.orderRefs: shop entries still posted under an old key, and where each belongs.
• ledger.proposals: reconciliation runs and what each proposed.

Set up the books (asks a person)

• ledger.createEntity: start books for a business with the default chart.
• ledger.updateEntity: rename, archive, bring back, or make the default.
• ledger.createAccount: add an account to an entity's chart.
• ledger.updateAccount: rename, archive or bring back an account.
• ledger.seedMissingAccounts: add the accounts the default chart has gained since the entity was made.
• ledger.linkSource: say whose books a shop's, vault's or project's money goes to.
• ledger.unlinkSource: take back such a link. Destructive.
• ledger.mapSource: say which account a source object books to, from now on.
• ledger.unmapSource: take back such a map. Destructive.

Book and correct (asks a person)

• ledger.post: book a manual entry that balances per currency. Spends.
• ledger.reverse: reverse an entry with a mirrored one. Destructive.
• ledger.reclassify: move a flagged entry's money from suspense or a fallback account to the right accounts. Spends.
• ledger.markReviewed: clear the flag on an entry a person has checked.
• ledger.orderCosts: record what many orders cost, from the exported CSV. Spends.
• ledger.moveOrderRefs: move old shop entries to their order's key. Destructive.

Periods and reconciliation (asks a person)

• ledger.lockPeriod: lock a month of one entity. Destructive.
• ledger.unlockPeriod: reopen a locked month, with a reason. Destructive.
• ledger.importStatement: import a bank or provider statement for one account and period.
• ledger.reconcile: compare an imported statement with the books and propose matches and differences.
• ledger.decideProposal: confirm or reject a proposal, with a note.

Over MCP the same tools are named ledger__post and so on (API keys and MCP access).

Related

• Money
• Exchange rates and stuck entries
• Costs
• Vaults
• Invoices
• Bills
• Extraction
• Accounts: exchange rates.