Method

account.create

Create an account under a parent (the root by default).

Adds an account to the open book, under the root or under the parent you name, as GnuCash's New Account dialog does. Give it a name, a type (BANK, CASH, ASSET, CREDIT, LIABILITY, STOCK, MUTUAL, INCOME, EXPENSE, EQUITY, …) and the commodity its amounts are in; a currency can be named by its code alone (USD). Accounts are then named by their full name, levels joined with :, or by the GUID this method returns.

Examples

A bank account under a new top-level asset account:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Assets","type":"ASSET","commodity":"USD","placeholder":true}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "…",
    "name": "Assets",
    "fullName": "Assets",
    "placeholder": true,
    "…": "…"
  }
}

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Checking","type":"BANK","parent":"Assets","commodity":"USD"}}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "guid": "…",
    "name": "Checking",
    "fullName": "Assets:Checking",
    "type": "BANK",
    "parent": "…",
    "commodity": "CURRENCY::USD",
    "scu": 100,
    "depth": 2,
    "…": "…"
  }
}

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Assets","type":"ASSET","commodity":"USD","placeholder":true}
account.create {"name":"Checking","type":"BANK","parent":"Assets","commodity":"USD"}
EOF

[
  {
    "guid": "…",
    "name": "Assets",
    "fullName": "Assets",
    "placeholder": true,
    "…": "…"
  },
  {
    "guid": "…",
    "name": "Checking",
    "fullName": "Assets:Checking",
    "type": "BANK",
    "parent": "…",
    "commodity": "CURRENCY::USD",
    "scu": 100,
    "depth": 2,
    "…": "…"
  }
]

{"name":"account.create","arguments":{"name":"Assets","type":"ASSET","commodity":"USD","placeholder":true}}

{
  "structuredContent": {
    "guid": "…",
    "name": "Assets",
    "fullName": "Assets",
    "placeholder": true,
    "…": "…"
  }
}

{"name":"account.create","arguments":{"name":"Checking","type":"BANK","parent":"Assets","commodity":"USD"}}

{
  "structuredContent": {
    "guid": "…",
    "name": "Checking",
    "fullName": "Assets:Checking",
    "type": "BANK",
    "parent": "…",
    "commodity": "CURRENCY::USD",
    "scu": 100,
    "depth": 2,
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of account.create.

• name (string, required): Name: not empty, without :, and unlike its siblings'.
• type (string, required): Account type (see account.types); it must suit the parent's.
• parent (AccountRef or null): Parent; the root by default.
• 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.