---
title: "Update ledgers (general ledger accounts)"
method: PUT
path: "/books/ledgers"
tags: ["Books"]
---

# Update ledgers (general ledger accounts)

`PUT /books/ledgers`

## Request

- Base URL: `https://api.mercury.com/api/v1`
- URL: `https://api.mercury.com/api/v1/books/ledgers`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mercurytechnologies/apis/mercury-api/docs/books/ledgers/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates up to 100 existing ledgers, i.e. general ledger (GL) accounts, in the organization's live chart of accounts: rename (`name`), renumber (`sortCode`, the account number), re-parent (`parentId`), or retype (`type`, `subType`, `debitCredit`) them. To find ledger IDs, use getBooksLedgers. Each item names a `ledgerId` and only the fields to change; omitted fields are left unchanged. To remove a ledger's parent, list `parentId` in `clearFields` (and don't also set `parentId`). Each `ledgerId` may appear at most once.

**Chart-of-accounts rules.** Teal validates each update: `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, so a sub-ledger can't be retyped in place; a parent can't be the ledger itself or one of its descendants; names and sort codes must be unique; required ledgers allow changes only to `name`, `sortCode`, and `parentId`; expense and revenue ledgers can't be cash-flow ledgers, so a cash-flow ledger can't be retyped to either; and ledgers linked to a financial account may refuse some changes.

**Per-item results.** The response has exactly one result per requested update, in request order: the updated ledger, in the same shape as getBooksLedgers returns, or an `error` with a stable `code` and a `message` saying how to fix it. A ledger that fails does not fail the request or the other ledgers, so the status is 200 even when some or all fail; check each result. Error codes include `invalidLedger`, `missingParameters`, `duplicateName`, `duplicateSortCode`, `invalidLedgerType`, `invalidLedgerParent`, `invalidLedgerReportCashFlow`, `modifyingRequiredLedger`, and `unknownError`; treat any code not listed here as `unknownError`.

**Request errors.** These are returned as an HTTP error status, and nothing is updated: the token lacks the scope to update ledgers; a ledger or new parent ledger is outside the Books instance or read-only (linked to a Mercury account); the list is empty; it has more than 100 updates; or a `ledgerId` is repeated.

## 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

- UpdateBooksAPILedgersRequest: Request to update general ledgers.
  - `ledgers` UpdateBooksAPILedger[], required: The ledger updates to apply, from 1 to 100 ('maxBooksAPILedgerWrites'), processed in order. Each `ledgerId` may appear at most once.
    - `clearFields` BooksLedgerClearField[], nullable: Fields to clear, such as the parent ledger
    - `debitCredit` 'debit' | 'credit', nullable: Updated debit or credit nature
    - `ledgerId` string, base58 (max length 22), required: The ID of the ledger to update
    - `name` string, size < 256, nullable: Updated ledger name
    - `parentId` string, base58 (max length 22), nullable: Updated parent ledger
    - `sortCode` string, matches ^[0-9]+$, size < 21, nullable: Updated numeric sort code
    - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings', nullable: Updated ledger sub-type
    - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense', nullable: Updated ledger type

## Response `200`

- UpdateBooksAPILedgersResponse: One result per requested ledger update, in request order.
  - `results` BooksAPIUpdateLedgerResult[], required: One result per requested ledger update, in request order. A failed item does not fail the others.
    - `error` object, nullable: Why the ledger was not updated, 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 updated ledger, when it was updated.
      - `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/put.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)