budget.setAmounts

Set or unset many budget amounts, atomically.

Sets or unsets many budget amounts at once, all or none. Each cell is an account and a period (counting from 0); an amount sets it, null unsets it, and "0" is a set zero, which is not the same as unset. Amounts are kept exactly as given ("750.00" is stored as 75000/100) in natural signs: expense budgets positive, income budgets negative.

Refused with invalid: a period at or beyond the budget's count (GnuCash silently does nothing), the same cell twice in one call, the root account. Placeholder and hidden accounts may have amounts.

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":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}}

Response:

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

Request:

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

Response:

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

Request:

{"jsonrpc":"2.0","id":4,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000003","amounts":[{"account":"Rent","period":0,"amount":"750.00"},{"account":"Rent","period":1,"amount":"750.00"},{"account":"Salary","period":0,"amount":"-3000.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "budget": "00ed0000000000000000000000000003",
    "set": 3,
    "unset": 0
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000003","amounts":[{"account":"Rent","period":9,"amount":"1"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": 2001,
    "message": "period 9 is past the budget's 6 periods (they count from 0)",
    "data": {
      "help": "error/invalid"
    }
  }
}

Command line

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

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2001,
    "message": "period 9 is past the budget's 6 periods (they count from 0)",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

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

Result:

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

Tool call:

{"name":"account.create","arguments":{"name":"Salary","type":"INCOME","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":"00ed0000000000000000000000000003","amounts":[{"account":"Rent","period":0,"amount":"750.00"},{"account":"Rent","period":1,"amount":"750.00"},{"account":"Salary","period":0,"amount":"-3000.00"}]}}

Result:

{
  "structuredContent": {
    "budget": "00ed0000000000000000000000000003",
    "set": 3,
    "unset": 0
  }
}

Tool call:

{"name":"budget.setAmounts","arguments":{"budget":"00ed0000000000000000000000000003","amounts":[{"account":"Rent","period":9,"amount":"1"}]}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "period 9 is past the budget's 6 periods (they count from 0)",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of budget.setAmounts.

budget (Guid, required): The budget.
amounts (array of AmountCell, required): The cells; each at most once.

Result

The result of budget.setAmounts.

budget (Guid, required): The budget.
set (integer (uint), required): Cells set.
unset (integer (uint), required): Set cells unset.