customer.list

Customers, optionally filtered by name, ID or active state.

Lists customers, in GUID order, optionally only the active ones or those whose name contains some text (any case) or whose ID matches exactly. Use it to find a customer's GUID from what you know of it.

Deactivated customers are listed unless activeOnly is set.

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.list","params":{"name":"acme"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "customers": [
      {
        "guid": "5b22073fa4e34411b07c14a77147ce6b",
        "name": "Acme & Sons <Ltd>",
        "…": "…"
      }
    ]
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"customer.list","params":{"name":"globex"}}

Response:

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

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
customer.list {"name":"acme"}
customer.list {"name":"globex"}
EOF

It prints:

[
  {
    "customers": [
      {
        "guid": "5b22073fa4e34411b07c14a77147ce6b",
        "name": "Acme & Sons <Ltd>",
        "…": "…"
      }
    ]
  },
  {
    "customers": []
  }
]

MCP tool call

Tool call:

{"name":"customer.list","arguments":{"name":"acme"}}

Result:

{
  "structuredContent": {
    "customers": [
      {
        "guid": "5b22073fa4e34411b07c14a77147ce6b",
        "name": "Acme & Sons <Ltd>",
        "…": "…"
      }
    ]
  }
}

Tool call:

{"name":"customer.list","arguments":{"name":"globex"}}

Result:

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

Effect: read.

Params

Filters for the contact lists. All given filters must match.

activeOnly (boolean): Only active contacts.
name (string or null): Case-insensitive part of the name.
id (string or null): The exact ID. IDs are not unique in GnuCash, so several may match.

Result

Customers.

customers (array of CustomerInfo, required): In GUID order.