---
title: "Set or clear ledger opening balances"
method: PUT
path: "/books/ledgers/opening-balances"
tags: ["Books"]
---

# Set or clear ledger opening balances

`PUT /books/ledgers/opening-balances`

## Request

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

Sets or clears the opening balance of up to 100 ledgers, i.e. general ledger (GL) accounts, in the organization's chart of accounts. To find ledger IDs, use getBooksLedgers; a ledger's current opening balance is its `openingBalance` there. Each item names a `ledgerId` and a `balance`; each `ledgerId` may appear at most once.

**How opening balances work.** Each ledger's opening balance is recorded on its own journal entry, dated the Books instance's entries start date and offset against the opening balances ledger. Setting a balance replaces any opening balance the ledger already has. A `balance` of `0` clears it.

**Sign of `balance`.** The balance is in the ledger's natural direction (its `debitCredit`): a positive balance increases the ledger on its natural side (a debit for debit-natural ledgers such as assets and expenses, a credit for credit-natural ledgers such as liabilities, equity, and revenue), and a negative balance puts it on the opposite side.

**Per-item results.** The response has exactly one result per requested ledger, in request order: its `ledgerId` and `success: true`, or `success: false` with an `error` that has 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` (for example the opening balances ledger itself, which can't carry an opening balance), and `unknownError`; treat any code not listed here as `unknownError`.

**Request errors.** These are returned as an HTTP error status, and nothing is set: the token lacks the scope to update ledgers; a ledger is outside the Books instance; a ledger is linked to a Mercury account, whose transaction history determines its balance, so its opening balance can't be set (403, naming the ledger IDs); the list is empty; it has more than 100 items; or a `ledgerId` is repeated.

## Query parameters

- `booksId` string, uuid: The Books instance to act on. Required for agent organization tokens; defaults to the token organization's instance.

## Request body

- SetBooksAPILedgerOpeningBalancesRequest: Request to set or clear the opening balances of ledgers.
  - `openingBalances` SetBooksAPILedgerOpeningBalance[], required: The opening balances to set, from 1 to 100 ('maxBooksAPIBulkWriteItems'), processed in order. Each `ledgerId` may appear at most once.
    - `balance` number, double, required: The ledger's opening balance in its natural direction: positive increases the ledger on its natural side (debit for debit-natural ledgers, credit for credit-natural ledgers), negative puts it on the opposite side. `0` clears the opening balance.
    - `ledgerId` string, base58 (max length 22), required: The ID of the ledger whose opening balance to set.

## Response `200`

- SetBooksAPILedgerOpeningBalancesResponse: One result per requested opening balance, in request order.
  - `results` BooksAPISetLedgerOpeningBalanceResult[], required: One result per requested opening balance, in request order. A failed item does not fail the others.
    - `error` object, nullable: Why the opening balance was not set, 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.
    - `ledgerId` string, base58 (max length 22), required: The ledger the requested opening balance was for.
    - `success` boolean, required: Whether the opening balance was set (or cleared).

## 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/opening-balances/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)