Books Reference

This page lists the fields, limits, and rules for Books in one place. For how Multi-Book works, see Multi-Book Accounting; for the steps, see How to Set Up and Manage Books and How to Assign Books to Records.

Book fields

A Book has the fields below. You set them on the New Book drawer under Configuration → Accounting Setup → Books, and the API returns them under the names shown.

Field	API name	Type	Required	Default	Description
Name	`name`	string	Yes	None	The name shown in Book selectors, report filters, and record Activity. Editable, including on the Primary Book.
Code	`code`	string	Yes	None	A short identifier of up to 20 characters, unique in the organization across active and inactive Books. Stored in uppercase. Can’t be changed after the Book is created.
Description	`description`	string	No	Empty	Free text describing the Book.
Status	`is_active`	boolean	No	Active (`true`)	Whether new records can go to the Book. Inactive Books keep their existing records.
Not shown	`is_default`	boolean	N/A	`false`	`true` for the Primary Book only. Shown in the app as Primary next to the Book’s name.
Not shown	`id`	integer	N/A	Assigned	The Book’s identifier, used in `book_ids` on records.

Limits and Primary Book rules

The rules below apply to every organization with Multi-Book.

Rule	Value
Active Books per organization	Five at most, including the Primary Book. Reactivating a Book counts toward the limit.
Primary Book	Exactly one, created automatically with the name Primary and the code `PRIMARY`. It can be renamed but not deactivated, and it can’t receive a historical records sync.
Deleting a Book	Not available. Deactivate the Book instead.
Historical records syncs	One queued or running sync per Book. The source and the target must both be active and must be different Books.
Currency	Books have no currency of their own. Every Book reports in your companies’ currencies.

Which Books each record posts to

The table below shows where each record type gets its Books, with the organization setting Allow Book selection on all records off (the default) and on. “All active Books” means every Book that is active when the record is created.

Record type	Setting off	Setting on
Journal entry	The Books you select, or all active Books if you select none.	Same as setting off.
Invoice, bill, customer or vendor payment, customer or vendor credit, refund, prepayment, prepayment application, deposit, cash sale, direct expense, bank transfer, intercompany journal entry, allocation journal	All active Books.	The Books you select, or all active Books if you select none.
Contract	All active Books.	The Books you select, or all active Books if you select none.
Records a contract generates: linked invoices, customer credits, change orders, terminations, adjustments, revenue recognition entries	The contract’s Books.	The contract’s Books.
Amortization (prepaid expense)	All active Books.	The Books you select, or all active Books if you select none.
Amortization schedule entries	The amortization’s Books.	The amortization’s Books.
Fixed asset	All active Books.	All active Books.
Depreciation, disposal, and revaluation entries	The fixed asset’s Books.	The fixed asset’s Books.
Inventory transactions	All active Books.	All active Books.
Reversing and elimination entries	The Books of the record they belong to.	The Books of the record they belong to.
Records created by CSV import or bulk import	All active Books.	All active Books.

Two rules apply on top of the table:

Linked records match: a payment, refund, or prepayment application must have exactly the same Books as every posted record it applies to. Drafts aren’t checked until they’re posted.
Changes after creation: with the setting off, only journal entries can change to a different set of Books. Changing a contract’s Books changes the Books on every record it generated.

Reports and the Book filter

Reports that read general ledger data have a Book filter. It lists active Books, with the Primary Book first and marked (Primary). When you don’t choose a Book, the report shows the Primary Book. The table below groups reports by how they use Books.

Report group	Book behavior
Income statement, balance sheet, statement of cash flows, trial balance (summary and detail), GL detail, AR aging, AP aging, and other reports built on general ledger data	Filtered by the Book you choose, or the Primary Book by default.
Fixed asset register and fixed asset rollforward	Filtered by depreciation book, not by GL Book.
Inventory valuation, inventory activity, three-way match, revenue waterfall, invoice waterfall, ARR by contract, ownership reports, withholding tax register	Not affected by Books.

The filter takes one Book at a time. For why there is no combined view, see Reporting by Book.

Record Activity

Changes to a record’s Books appear in its Activity as “Books from” the previous Books “to” the new Books, with Book names. An empty side shows as “(none)”.

Event	Logged in record Activity
Books changed on a record	Yes, when the set of Books actually changes
Books changed on a contract	Yes, once on the contract, not on each record it generated
Historical records sync	No. Each run appears in the Book’s sync history instead.
Book assignments made before Book changes were logged	No

API, CLI, and MCP

The public API reads Books and sets them on journal entries and contracts. Each endpoint below is also available under /public/v3-alpha/.

Endpoint	What it does with Books
`GET /public/v2/books/`	Lists Books with `id`, `code`, `name`, `description`, `is_default`, and `is_active`. Filter with `search`, `id`, `code`, and `is_active`.
`GET /public/v2/books/{book_id}/`	Returns one Book.
`POST /public/v2/journal-entries/`	Accepts `book_ids`, an array of Book IDs. Omit it or send `null` or an empty array to post to all active Books.
`PUT /public/v2/journal-entries/{record_number}/`	Accepts `book_ids` the same way. Omitting it assigns all active Books, so send the full list on every update to keep a selection.
`PUT /public/v2/contracts/{record_id}/`	Accepts `book_ids`. A changed set is rejected while Allow Book selection on all records is off.
`POST /public/v2/contracts/` and `POST /public/v2/invoices/`	Don’t accept `book_ids`. A new contract goes to all active Books, and an invoice goes to all active Books or, when it’s linked to a contract, to the contract’s Books.

Journal entry, contract, contract change order, and revenue recognition responses include book_ids. Other record types don’t take or return Books through the public API, so they get their Books by the rules in Which Books each record posts to. The API returns these validation errors under the book_ids key:

Select exactly the same books as every posted linked record.
Book selection is disabled for this organization.
All selected books must be active and belong to this organization.

CLI and MCP

The DualEntry CLI has no command for Books. dualentry depreciation-books lists fixed asset depreciation books, such as BOOK and FEDERAL, which are separate from GL Books. The DualEntry MCP server has no Book-specific tool.

Multi-Book Accounting: how Books and Book assignment work
How to Set Up and Manage Books: create, sync, and deactivate Books
How to Assign Books to Records: choose and change Books on records
Aging Reports Reference: AR and AP aging, which respect the Book filter

Get Started

Core Financials

Revenue Recognition

Reporting and Analytics

Platform Configuration

AI and Automation

Integrations

Book fields

Limits and Primary Book rules

Which Books each record posts to

Reports and the Book filter

Record Activity

API, CLI, and MCP

CLI and MCP

Book fields

Limits and Primary Book rules

Which Books each record posts to

Reports and the Book filter

Record Activity

API, CLI, and MCP

CLI and MCP

Related pages