Method

account.update

Change an account's name, type, commodity, smallest fraction, code, notes, flags, tax settings, colour, balance limits, opening balance flag or associated accounts.

Changes an account's name, type, commodity, smallest fraction, code, description, notes, flags (placeholder, hidden), tax settings, colour, balance limits, opening balance flag or associated accounts. A field you leave out is kept; an empty string clears a text field.

GnuCash's account dialog rules apply. The commodity can change only while the account has no splits, and a type only to one in changesWithSplits once it has; changing a type that sub-accounts cannot sit under needs retypeChildren: true. A new name must not clash with a sibling's and may not contain :. Existing amounts are not re-rounded when scu changes.

Examples

{"jsonrpc":"2.0","id":1,"method":"account.update","params":{"account":"Root:Asset:Wallet","code":"110","description":"Cash on hand"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "fullName": "Root:Asset:Wallet",
    "code": "110",
    "description": "Cash on hand",
    "…": "…"
  }
}

red-ale exec --book book.gnucash account.update '{"account":"Root:Asset:Wallet","code":"110","description":"Cash on hand"}'

{
  "fullName": "Root:Asset:Wallet",
  "code": "110",
  "description": "Cash on hand",
  "…": "…"
}

{"name":"account.update","arguments":{"account":"Root:Asset:Wallet","code":"110","description":"Cash on hand"}}

{
  "structuredContent": {
    "fullName": "Root:Asset:Wallet",
    "code": "110",
    "description": "Cash on hand",
    "…": "…"
  }
}

The commodity of an account with transactions cannot change:

{"jsonrpc":"2.0","id":1,"method":"account.update","params":{"account":"Root:Asset:Bank","commodity":"EUR"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "help": "error/conflict"
    }
  }
}

red-ale exec --book book.gnucash account.update '{"account":"Root:Asset:Bank","commodity":"EUR"}'

{
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "help": "error/conflict"
    }
  }
}

{"name":"account.update","arguments":{"account":"Root:Asset:Bank","commodity":"EUR"}}

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "…",
      "data": {
        "help": "error/conflict"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of account.update.

• account (AccountRef, required): The account.
• name (string or null): New name.
• type (string or null): New type. With splits, only a compatible type (see account.types).
• retypeChildren (boolean): Confirm that sub-accounts whose type cannot sit under the new type take the new type too.
• commodity (CommodityId or null): Commodity: a currency for most types, a security for STOCK and MUTUAL. On create, defaults to the parent's when it suits the type. Cannot change once the account has splits.
• scu (ScuParam or null): Smallest fraction.
• code (string or null): Account code; empty clears it.
• description (string or null): Description; empty clears it.
• notes (string or null): Notes; empty clears them.
• placeholder (boolean or null): Placeholder flag.
• hidden (boolean or null): Hidden flag.
• taxRelated (boolean or null): Tax-related flag.
• taxUsCode (string or null): US TXF code; empty clears it.
• taxUsPayerNameSource (string or null): US TXF payer name source (current or parent); empty clears it.
• taxUsCopyNumber (integer (int64) or null): US TXF copy number; 0 clears it.
• color (string or null): Account colour: #rrggbb, #rgb or rgb(r,g,b), stored as rgb(r,g,b); empty (or GnuCash's default rgb(237,236,235)) clears it.
• higherBalanceLimit (Amount or null): Higher balance limit, in raw sign; null clears it.
• lowerBalanceLimit (Amount or null): Lower balance limit, in raw sign; null clears it.
• includeSubaccountBalances (boolean or null): Apply the balance limits to the balance with sub-accounts. Cleared when no limit is left.
• openingBalance (boolean or null): Hold the opening balances of the account's commodity (EQUITY only; one per commodity; not once it has splits). Setting it declares GnuCash's opening balance account Book feature.
• associatedAccounts (map of AccountRef or null or null): Associated accounts by tag; null removes a tag, tags not named are kept.

Result

An account.

• guid (Guid, required): GUID.
• name (string, required): Name.
• fullName (string, required): Full name: ancestors' names joined by :, without the root.
• type (string, required): Account type, as GnuCash writes it.
• parent (Guid or null): Parent; none only for the root.
• commodity (CommodityId or null): Commodity held.
• scu (integer (int64), required): Smallest fraction the account's amounts are kept in.
• nonStandardScu (boolean, required): The smallest fraction was chosen instead of the commodity's.
• code (string or null): Account code.
• description (string or null): Description.
• notes (string or null): Notes.
• placeholder (boolean, required): Groups other accounts; GnuCash's register refuses splits in it.
• hidden (boolean, required): Hidden itself.
• hiddenInTree (boolean, required): Hidden itself or through an ancestor, as GnuCash shows it.
• taxRelated (boolean, required): Tax-related.
• taxUs (TaxUs, required): US tax (TXF) settings.
• depth (integer (uint), required): Levels below the root (top-level accounts are 1).
• children (integer (uint), required): Number of immediate sub-accounts.
• hasSplits (boolean, required): The account has splits.
• color (string or null): Account colour (rgb(r,g,b) as GnuCash's dialog writes it, or as stored); null when unset or Not Set.
• higherBalanceLimit (Amount or null): Higher balance limit, in raw sign (debits positive).
• lowerBalanceLimit (Amount or null): Lower balance limit, in raw sign.
• includeSubaccountBalances (boolean, required): The balance limits apply to the balance with sub-accounts.
• openingBalance (boolean, required): The EQUITY account holding the opening balances of its commodity.
• associatedAccounts (map of Guid, required): Associated accounts by tag (such as stock-dividends), each naming an existing account.