Method

customer.update

Change a customer; `active: false` deactivates it.

Changes the fields of a customer you name; fields you leave out stay as they are. null clears a field that can be empty (terms, taxTable), and addr and shipAddr merge field by field, so {"addr": {"phone": "555-9999"}} changes the phone number alone.

There is no way to delete a customer, as there is none in GnuCash: its documents would be left without an owner. Set active: false instead. A deactivated customer is still in the book and keeps its documents.

Examples

Example: with a copy of the synthetic/business-editable example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"customer.update","params":{"customer":"5b22073fa4e34411b07c14a77147ce6b","active":false,"addr":{"phone":"555-9999"}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "5b22073fa4e34411b07c14a77147ce6b",
    "addr": {
      "name": "Acme Billing",
      "addr1": "1 Main St",
      "phone": "555-9999",
      "…": "…"
    },
    "active": false,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"customer.list","params":{"activeOnly":true}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "customers": []
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
customer.update {"customer":"5b22073fa4e34411b07c14a77147ce6b","active":false,"addr":{"phone":"555-9999"}}
customer.list {"activeOnly":true}
EOF

It prints:

[
  {
    "guid": "5b22073fa4e34411b07c14a77147ce6b",
    "addr": {
      "name": "Acme Billing",
      "addr1": "1 Main St",
      "phone": "555-9999",
      "…": "…"
    },
    "active": false,
    "…": "…"
  },
  {
    "customers": []
  }
]

MCP tool call

Tool call:

{"name":"customer.update","arguments":{"customer":"5b22073fa4e34411b07c14a77147ce6b","active":false,"addr":{"phone":"555-9999"}}}

Result:

{
  "structuredContent": {
    "guid": "5b22073fa4e34411b07c14a77147ce6b",
    "addr": {
      "name": "Acme Billing",
      "addr1": "1 Main St",
      "phone": "555-9999",
      "…": "…"
    },
    "active": false,
    "…": "…"
  }
}

Tool call:

{"name":"customer.list","arguments":{"activeOnly":true}}

Result:

{
  "structuredContent": {
    "customers": []
  }
}

Effect: write, on the Book.

Params

Params of customer.update: the fields to change.

  • customer (Guid, required): The customer.
  • name (string or null): Company name.
  • id (string or null): Customer number. On create, absent or empty takes the next number from the book's gncCustomer counter.
  • currency (CommodityId or null): The currency of the customer's documents.
  • addr (AddressParams or null): Billing address.
  • shipAddr (AddressParams or null): Shipping address.
  • notes (string or null): Notes.
  • terms (BillTermRef or null): Default billing term for new invoices, by GUID or name; null for none.
  • taxTable (TaxTableRef or null): Tax table, by GUID or name; null for none.
  • taxTableOverride (boolean or null): New invoice lines use taxTable rather than the book's default.
  • taxIncluded (TaxIncludedWire or null): Whether prices include tax by default.
  • discount (Amount or null): Default discount percentage for new invoice lines, 0 to 100.
  • credit (Amount or null): Credit limit.
  • active (boolean or null): Active; false deactivates.

Result

A customer.

  • guid (Guid, required): A GUID: 32 hexadecimal digits.
  • id (string, required)
  • name (string, required)
  • addr (AddressInfo, required): An address. Empty strings are unset fields.
  • shipAddr (AddressInfo, required): An address. Empty strings are unset fields.
  • notes (string, required)
  • currency (CommodityId or null)
  • terms (Guid or null)
  • taxTable (Guid or null)
  • taxTableOverride (boolean, required)
  • taxIncluded (TaxIncludedWire, required): Whether prices include tax by default for the contact's documents.
  • discount (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number.
  • credit (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number.
  • active (boolean, required)