counter.set

Set a counter's last number issued or its format; a null or empty format means the default.

Sets a counter's last number issued (last) or its format. A format is a C-style printf pattern for a long, such as INV-%04li; a null or empty format means the default. formatValid says whether the pattern is one GnuCash accepts, and next is the ID the counter will give next, so check it before relying on the format.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"counter.set","params":{"name":"gncInvoice","last":41}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "name": "gncInvoice",
    "last": 41,
    "format": null,
    "next": "000042",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"counter.set","params":{"name":"gncInvoice","format":"INV-%04li"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "name": "gncInvoice",
    "last": 41,
    "format": "INV-%04li",
    "formatValid": true,
    "next": "INV-0042",
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
counter.set {"name":"gncInvoice","last":41}
counter.set {"name":"gncInvoice","format":"INV-%04li"}
EOF

It prints:

[
  {
    "name": "gncInvoice",
    "last": 41,
    "format": null,
    "next": "000042",
    "…": "…"
  },
  {
    "name": "gncInvoice",
    "last": 41,
    "format": "INV-%04li",
    "formatValid": true,
    "next": "INV-0042",
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"counter.set","arguments":{"name":"gncInvoice","last":41}}

Result:

{
  "structuredContent": {
    "name": "gncInvoice",
    "last": 41,
    "format": null,
    "next": "000042",
    "…": "…"
  }
}

Tool call:

{"name":"counter.set","arguments":{"name":"gncInvoice","format":"INV-%04li"}}

Result:

{
  "structuredContent": {
    "name": "gncInvoice",
    "last": 41,
    "format": "INV-%04li",
    "formatValid": true,
    "next": "INV-0042",
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of counter.set.

name (string, required): One of gncCustomer, gncEmployee, gncInvoice, gncBill, gncExpVoucher, gncJob, gncOrder, gncVendor.
last (integer (int64) or null): The last number issued, from 0 to 999999999; the next ID uses one more.
format (string or null): A printf format with one %li, %lli or %I64i conversion; null or empty removes it.

Result

A counter.

name (string, required): Its name in the book, such as gncInvoice.
last (integer (int64), required): The last number issued; 0 when none.
format (string or null): The format as stored, if any.
formatValid (boolean, required): GnuCash accepts the stored format; when false it numbers with the default.
normalizedFormat (string, required): The format GnuCash numbers with: the stored one normalised, else the default %.6li.
next (string, required): The ID the next object would get. Reading it does not take it.