> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentaos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> List the people who have paid you, from the terminal.

`agenta customers` is a quick lookup for anyone who has ever completed a checkout with you: email, name, country, VAT number if they gave one. Read-only from the CLI today.

```bash theme={"system"}
agenta customers list
```

## Usage

```bash theme={"system"}
agenta customers list [--limit <n>] [--json]
```

<ParamField query="--limit" type="number" default="10">
  Results per page, 1 to 100.
</ParamField>

<ParamField query="--json" type="boolean">
  Output a single JSON object instead of a table.
</ParamField>

```bash Output theme={"system"}
  Customers (2 total)

  jane@startup.io               Jane Cooper              DE   10f6f205-0f31-44c3-ad1a-240af6177e74
  ana@example.com                Ana Reyes                 ES   f5100f77-fd73-4c33-a6e7-c1c5db53804c

  2 of 2 shown.
```

### `--json`

```json theme={"system"}
{
  "total": 2,
  "hasMore": false,
  "items": [
    {
      "id": "10f6f205-0f31-44c3-ad1a-240af6177e74",
      "email": "jane@startup.io",
      "name": "Jane Cooper",
      "country": "DE",
      "vatNumber": "DE123456789",
      "stripeCustomerId": "cus_Q4f...",
      "createdAt": "2026-06-11T09:15:00.000Z"
    }
  ]
}
```

## Fields

| Field | Description |
| - | - |
| `id` | Customer ID, e.g. `10f6f205-0f31-44c3-ad1a-240af6177e74`. |
| `email` | Buyer's email. |
| `name` | Buyer's name, `null` if never provided. |
| `country` | ISO 3166-1 alpha-2 country code (`DE`, `US`), `null` if unknown. |
| `vatNumber` | Buyer's VAT number if they entered one at checkout. |
| `stripeCustomerId` | Underlying customer from the card processor, for card and bank payments. |
| `createdAt` | When this customer record was first created. |

<Tip>
  Piping `agenta customers list` to a file or another command switches to JSON automatically, no `--json` needed: `agenta customers list --limit 100 > customers.json`.
</Tip>

## Next steps

<Columns cols={2}>
  <Card title="Subscriptions" icon="arrows-rotate" href="/cli/subscriptions">
    See what a customer is subscribed to.
  </Card>

  <Card title="Invoices" icon="file-invoice-dollar" href="/cli/invoices">
    Pull a customer's paid invoices and receipts.
  </Card>

  <Card title="Customers (SDK)" icon="code" href="/sdk/pay-customers">
    Look up customers from your own backend.
  </Card>

  <Card title="Customers (concept)" icon="book" href="/payments/customers">
    How customer records are created and used.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.