---
title: "Update a portfolio account"
method: PATCH
path: "/v1/portfolios/{portfolioSlug}/accounts/{accountNumber}"
tags: ["Accounts"]
---

# Update a portfolio account

`PATCH /v1/portfolios/{portfolioSlug}/accounts/{accountNumber}`

## Request

- Base URL: `https://api.tokenbooks.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tokenbooks.io/v1/portfolios/{portfolioSlug}/accounts/{accountNumber}`
- Auth: API key in header `x-api-key`

Applies the supplied fields to one Chart of Accounts row. Omitted fields are unchanged and an explicit null parentAccountNumber detaches the account. A newly requested parent must have the same account type as the child and must not carry journal activity. Returning the canonical account response also requires ledger-account view permission. Advanced Ledger is required after the existing account permissions; unavailable Advanced Ledger returns HTTP 403 (FeatureNotEnabledError).

## Path parameters

- `accountNumber` string, required
- `portfolioSlug` string, required

## Request body

- UpdateAccountRequestDto
  - `accountNumber` string: New portfolio-unique ledger account number.
  - `name` string: New ledger account name.
  - `isActive` boolean: New active state.
  - `parentAccountNumber` string, nullable: New parent account number, or null to detach from any parent.
  - `paymentLabel` string, nullable: New payment label, or null to clear it.

## Response `200`

The account after the update in the shared account row shape.

- AccountResponseDto
  - `accountNumber` string, required: Ledger account number.
  - `name` string, required: Ledger account name.
  - `paymentLabel` string, nullable, required: Optional label shown in payment account selection.
  - `accountType` 'ASSET' | 'LIABILITY' | 'EQUITY' | 'INCOME' | 'EXPENSE', required: Top-level account type.
  - `subType` string, required: Persisted account subtype.
  - `normalBalanceType` 'DR' | 'CR', required: Debit or credit normal-balance side.
  - `isActive` boolean, required: Whether the account is currently marked active.
  - `origin` 'SYSTEM_MANAGED' | 'SYSTEM_DEFAULT' | 'USER_MANAGED', required: Which code path created this account: engine-managed, engine fallback, or user-created. A user-created value may also mean the one-time backfill migration could not disambiguate an older row.
  - `createdBy` object, nullable, required: Creator of a user-created account, when known. Null for system-generated accounts and for accounts created before creator tracking existed.
    - `userId` string, required
  - `hierarchy` object, required
    - `parentAccountNumber` string, nullable, required: Parent ledger account number, or null for a root account.
    - `depth` integer, required: Hierarchy depth.
    - `hasChildren` boolean, required: Whether the account has direct child accounts.
    - `isFilterContext` boolean, required: Whether the row is included only as ancestor context for a direct filter match.
  - `asset` object, nullable, required
    - `assetId` string, required: Public asset identifier.
    - `symbol` string, required: Asset symbol.
  - `currency` object, required
    - `assetId` string, required: Public currency asset identifier.
    - `symbol` string, required: Currency symbol.
  - `wallet` object, nullable, required
    - `chainId` string, required: Chain ID
    - `address` string, required: Wallet address
    - `name` string, required: Wallet display name.
  - `balance` object
    - `currentBalance` string, required: Draft-inclusive operational balance in the account currency across all journal statuses, with the normal-balance side positive.

## Other responses

- `409`

---

[API](https://skmtc.dev/tokenbooks/apis/tokenbooks-public-api.md) · [All operations](https://skmtc.dev/tokenbooks/apis/tokenbooks-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenbooks/apis/tokenbooks-public-api/revisions/180622e6255e?raw)