Method

budget.update

Change a budget's name, description, number of periods or recurrence.

Changes a budget's name, description, number of periods or recurrence.

Lowering numPeriods hides amounts and notes beyond the new count but does not delete them: they stay in the book, hidden counts them, and raising the count shows them again, as in GnuCash, which has no way to drop them. Changing the recurrence moves no amount: amounts belong to a period number, so only the dates of the periods change.

Examples

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"budget.create","params":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":4,"amount":"750.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"budget.update","params":{"budget":"00ed0000000000000000000000000002","numPeriods":3}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "numPeriods": 3,
    "amounts": [],
    "hidden": {
      "amounts": 1,
      "notes": 0
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Rent","type":"EXPENSE","commodity":"USD"}
budget.create {"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}
budget.setAmounts {"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":4,"amount":"750.00"}]}
budget.update {"budget":"00ed0000000000000000000000000002","numPeriods":3}
EOF

It prints:

[
  "…",
  "…",
  "…",
  {
    "numPeriods": 3,
    "amounts": [],
    "hidden": {
      "amounts": 1,
      "notes": 0
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"budget.create","arguments":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"budget.setAmounts","arguments":{"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":4,"amount":"750.00"}]}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"budget.update","arguments":{"budget":"00ed0000000000000000000000000002","numPeriods":3}}

Result:

{
  "structuredContent": {
    "numPeriods": 3,
    "amounts": [],
    "hidden": {
      "amounts": 1,
      "notes": 0
    },
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of budget.update; absent fields are left alone.

  • budget (Guid, required): The budget.
  • name (string or null): The new name.
  • description (string or null): The new description.
  • numPeriods (integer (uint32) or null): The new number of periods, 1 to 60. Lowering it hides amounts and notes beyond it but keeps them.
  • recurrence (Recurrence or null): The new recurrence: never once, weekend adjustment none. No amount moves.

Result

A budget.

  • guid (Guid, required): Identity.
  • name (string, required): The name.
  • description (string, required): The description.
  • numPeriods (integer (uint32), required): The number of periods.
  • recurrence (Recurrence, required): The recurrence that gives the periods' dates, as stored.
  • isDefault (boolean, required): True for the default budget.
  • periods (array of PeriodInfo or null): Each period below numPeriods; absent in budget.list.
  • amounts (array of AmountInfo or null): Every set amount of an account in the tree below numPeriods, by account full name then period; absent in budget.list.
  • notes (array of NoteInfo or null): Every note likewise; absent in budget.list.
  • hidden (SlotCounts, required): Amounts and notes kept at or beyond numPeriods.
  • orphaned (SlotCounts, required): Amounts and notes kept for GUIDs that name no account.