# list_customers

Returns matching customer/install rows and totals, with app scope and dataStatus.

## Purpose

Search and rank merchants: status, plan, current $/mo, lifetime revenue, contact email. Call to find specific merchants, top payers, or recently churned accounts.

## Credentials and scope

Owner workspace credential. The credential determines tool visibility. For tools with appId, use the HeyCrust app UUID from list_apps; the dashboard app selector does not supply MCP arguments for you.

## Inputs

- `appId`: optional; string or null
- `query`: optional; string — Search by shop domain or shop name.
- `status`: optional; string; values: Subscribed, Installed, Uninstalled, Frozen
- `sort`: optional; string; values: recent, clv, amr, oldest; default: "recent"
- `limit`: optional; integer; minimum: 1; maximum: 100; default: 25

## Example request

The identifiers and merchant are fictional. Replace them with records returned for your own workspace; this example is schema-checked, not a promise that the fictional record exists.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customers",
    "arguments": {
      "appId": "11111111-1111-4111-8111-111111111111",
      "query": "example",
      "status": "Subscribed",
      "sort": "recent",
      "limit": 25
    }
  }
}
```

POST this JSON to `https://heycrust.com/api/mcp` with `Content-Type: application/json` and `Authorization: Bearer <YOUR_CREDENTIAL>`. The tool result normally contains JSON encoded as text in `result.content`; inspect JSON-RPC errors and `result.isError` before using it.

## Result

Returns matching customer/install rows and totals, with app scope and dataStatus. This is a bounded list, not a full export.

## Effects and verification

Reads existing records or definitions. It does not create a payment or send a message. Verify the returned app/merchant identity and source coverage before interpreting the result.

## Troubleshooting

A missing tool can mean that the credential lacks its catalog or required scopes. Invalid arguments are different from unavailable source data or a record outside the workspace. A handler can return a business error even when the argument schema is valid. Read [MCP overview](/docs/mcp) and [Help](/docs/help).