--- title: "Create ledgers (general ledger accounts)" method: POST path: "/books/ledgers" tags: ["Books"] --- # Create ledgers (general ledger accounts) `POST /books/ledgers` ## Request - Base URL: `https://api.mercury.com/api/v1` - URL: `https://api.mercury.com/api/v1/books/ledgers` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates up to 100 ledgers, i.e. general ledger (GL) accounts, in the organization's live chart of accounts. Each ledger needs a name, type, subType, debitCredit (natural balance), and sortCode (account number), and may name a parentId to nest it under an existing ledger of the same Books instance that is not read-only. Teal validates each ledger against the chart-of-accounts rules: subType must belong to type (see the `type` and `subType` fields of a ledger, as returned by getBooksLedgers), a child ledger has the same type and sub-type as its parent, and names and sort codes must be unique. The response has exactly one result per requested ledger, in request order: the created ledger, in the same shape as getBooksLedgers returns, or an error with a stable `code` and a `message` explaining how to fix it. A failed ledger does not fail the request or the other ledgers, so the status is 200 even when some or all ledgers fail; check each result. Problems with the request as a whole, such as a missing scope, a parent ledger outside the Books instance or read-only (linked to a Mercury account), an empty list, or more than 100 ledgers, are reported with an HTTP error status and create nothing. ## Query parameters - `booksId` string, uuid: The Books instance to act on. Must be the token organization's own instance, which it defaults to. ## Request body - CreateBooksAPILedgersRequest: Request to create general ledgers. - `ledgers` CreateBooksAPILedger[], required: The ledgers to create, from 1 to 100 ('maxBooksAPILedgerWrites'). - `debitCredit` 'debit' | 'credit', required: Whether the ledger has a debit or credit nature - `name` string, size < 256, required: The ledger name - `parentId` string, base58 (max length 22), nullable: Optional parent ledger, to create this ledger as a child ledger - `sortCode` string, matches ^[0-9]+$, size < 21, required: Numeric sort code used to order the ledger in the chart of accounts - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings', required: The ledger sub-type - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense', required: The ledger type ## Response `200` - CreateBooksAPILedgersResponse: One result per requested ledger, in request order. - `results` BooksAPICreateLedgerResult[], required: One result per requested ledger, in request order. A failed item does not fail the others. - `error` object, nullable: Why the ledger was not created, when it wasn't. - `code` 'invalidLedger' | 'missingParameters' | 'duplicateName' | 'duplicateSortCode' | 'invalidLedgerType' | 'invalidLedgerParent' | 'invalidLedgerReportCashFlow' | 'deletingRequiredLedger' | 'deletingLedgerWithActivity' | 'deletingLinkedLedger' | 'deletingParentLedger' | 'modifyingRequiredLedger' | 'integrationMapped' | 'mercuryAccountLedger' | 'unknownError', required: Stable code for the failure. - `message` string, required: What went wrong and how to fix it, suitable to show to a user. - `ledger` object, nullable: The created ledger, when it was created. - `debitCredit` 'debit' | 'credit', required: Whether the ledger has a natural debit or credit balance. - `deletable` boolean, required: Whether the ledger can be deleted now. A ledger can't be deleted if it is required, has line entries, is linked to a bank or card account, or has an integration (invoicing, commerce, or a linked Plaid account) mapped to it. `deleteBlockedReason` says which. - `deleteBlockedReason` 'required' | 'hasActivity' | 'linkedSource' | 'integrationMapped', nullable: Why the ledger can't be deleted. Absent when `deletable` is true. When several reasons apply, only one is given: `required` first, then `linkedSource` for a ledger fed by a Mercury account, since neither can be fixed. Fixing any other reason may reveal another. - `editable` boolean, required: Whether line entries can be manually added to or removed from the ledger, for example by categorizing a transaction to it. False for ledgers whose activity a system controls, such as Mercury bank and card account ledgers and the accounts receivable and accounts payable required ledgers. - `financialAccountType` 'bankAccount' | 'creditCard' | 'payments' | 'payroll' | 'loan' | 'prepaidCard' | 'accountsReceivable' | 'accountsPayable' | 'investment' | 'treasury', nullable: The real-world financial account represented by this ledger, if any. - `id` string, base58 (max length 22), required: The stable identifier for the ledger. - `isRequired` boolean, required: Whether the ledger is a required ledger, which the accounting system needs to operate. Required ledgers can't be deleted, and only their `name`, `sortCode`, and `parentId` can be changed. - `name` string, size < 256, required: The ledger's display name. - `openingBalance` number, double, nullable: The ledger's opening balance in its natural direction (`debitCredit`): positive is a balance on the ledger's natural side, negative on the opposite side. Absent when the ledger has no opening balance. Returned by getBooksLedgers and getBooksLedger only; absent from the ledgers in create and update results. Set or clear it with setBooksLedgerOpeningBalances. - `parentId` string, base58 (max length 22), nullable: The identifier of the ledger's parent, if it is nested. - `requiredLedgerPurpose` 'uncatInflow' | 'uncatOutflow' | 'accountTransfers' | 'openingBalances' | 'accountsReceivable' | 'accountsPayable' | 'wagesExpense' | 'bonusExpense' | 'commissionsExpense' | 'contractorExpense' | 'employeeReimbursements' | 'severanceExpense' | 'payrollTaxExpense' | 'employerBenefitsExpense' | 'healthInsuranceExpense' | 'wagesPayable' | 'payrollTaxPayable' | 'employeeBenefitLiabilities' | 'payrollLiabilities' | 'payrollAdjustmentsClearing' | 'retainedEarnings' | 'currentYearEarnings' | 'benefitsExpense' | 'donationsExpense' | 'benefitsPayable' | 'payrollTaxAccruals' | 'stockExerciseClearing' | 'payrollClearing', nullable: The system function a required ledger fulfills, such as holding uncategorized inflows. Absent for ledgers that aren't required. - `sortCode` string, size < 21, required: The ledger/account number used for chart ordering and template mapping. - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings', required: The ledger's more specific accounting classification. It must belong to the ledger's `type`: `asset`: `currentAssets`, `nonCurrentAssets`, `transfersBetweenAccounts`, `uncategorizedAssets`; `liability`: `currentLiabilities`, `nonCurrentLiabilities`; `equity`: `equity`, `retainedEarnings`; `revenue`: `operatingRevenues`, `otherIncome`; `expense`: `costOfGoodsSold`, `operatingExpenses`, `otherExpenses`. A child ledger has the same type and sub-type as its parent. - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense', required: The ledger's top-level accounting classification. A sub-ledger has the same type as the root of its hierarchy. ## Other responses - `400`: Invalid `body` or `booksId` ## Changes - **2026-11-03** `95c77a617769`: 1 info - endpoint added [Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/ledgers/post.md) --- [API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) - [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mercurytechnologies/apis/mercury-api/revisions/95c77a617769?raw)