Skip to main content
A Book is a named measurement basis of one Entity. Use Books when a company must state the same facts under more than one measure, for example the financial statements its owners read and the return the tax authority reads. The two agree on most Entries; the differences (a depreciation rate, a provision the tax rule refuses, a correction the tax rule adds) are the Entries that name a Book. An Entity holds 0 to n Books. An Entity with no Book keeps one set of books, exactly as before. An Entity with at least one Book has more than one basis, so every book-scoped read must name which one with a bookId query parameter, and every write must state which Book its Entry counts in.

​
The model

  • Book. A named measurement basis of one Entity. Two Entities are free to use the same name.
  • Common Entry. A Ledger Entry with no bookId. It counts in every Book of the Entity.
  • Book Entry. A Ledger Entry that names a bookId. It counts in that Book only.
  • Report. Reads one Book: the common Entries plus the Entries of that Book.
The database enforces the structural half of the rule so a hand-written statement cannot break it:
  • A Book is unique by name inside one Entity.
  • An Entry cannot name a Book of another Entity (composite foreign key).
  • The Book of an Entry is set at insert and never moves. Correct a wrong Book by unbooking and reposting so the trail states the correction.
  • A Reversal stays in the Book of its original. A common Entry is reversed by a common Entry; a Book Entry by an Entry of that Book.
  • An Allocation settles two lines of one Book, or two common lines. Lines of different Books state no offset.

​
When bookId is required

Once an Entity has at least one Book, every book-scoped read must carry bookId, and the server answers BOOK_REQUIRED_ERROR (409) without it. An Entity with no Book must not send bookId. Book-scoped reads:
  • Home dashboard, balance sheet, income statement, income statement by dimension, journal, revenue realization, eight-column balance, general ledger, and partner ledger — see Reports.
  • Open item lines and match-candidates for a Bank Movement — see Ledger Entries and Bank Movements.
  • The paginated Partner listing (GET /partners/pages) — see Partners.
Two reads stay outside the rule and never name a Book: the Partner reference list (GET /partners), which an Invoice document embeds, and the Partner row returned by a create, an update, or a delete. Both surface open totals across every Book. Book-scoped writes carry bookId on the entry header of the Ledger Entry they post: create Ledger Entry, book Invoice, book Bank Movement, and match Bank Movement. A reversal takes the Book of its original — do not send bookId on POST /ledger/entries/:entryId/reverse.

​
GET /api/entities/:entityId/books

List the Books of the Entity in creation order.
  • Path param: entityId (UUID)
  • Success response: an array of Book objects (see Response shape)
  • Status: 200

​
POST /api/entities/:entityId/books

Create a Book under the Entity. The client supplies the idempotency id, so a retry with the same id is answered as a conflict instead of creating a duplicate.
  • Path param: entityId (UUID)
  • Body:

​
GET /api/entities/:entityId/books/:bookId

Read a single Book.
  • Path params: entityId (UUID), bookId (UUID)
  • Success response: the Book (see Response shape)
  • Status: 200

​
Response shape

Every endpoint on this page that returns a Book uses this shape:

​
Domain error codes

​
Status codes

​
What Books do not change

  • Chart of accounts. The Books of an Entity share its chart.
  • Currency. The Books of an Entity share its functional currency; presentation currency stays a report parameter.
  • Lock Date. The Entity’s ledger lock date closes every Book at once.
  • No primary Book. No Book is the default one; an Entity with Books names the Book it reads, every time.
  • No auto-derived Entries. A Book holds what a caller posted in it. Nothing copies, mirrors, or recomputes an Entry from one Book into another.
  • No rename, no delete. A Book is additive.