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

# List Customers

> Lista clientes.

Lista clientes vinculados à organização que está atuando, ordenados por
`created_at` decrescente. Use `starting_after`/`ending_before` para paginar.

## Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o
header `Organization: <organization_id>` apontando para uma organização
conectada ativa.

## Parâmetros de query

<ParamField query="limit" type="integer" default="10">
  Quantidade de itens por página. Entre `1` e `100`.
</ParamField>

<ParamField query="starting_after" type="string">
  ID do cliente que delimita o início da próxima página (exclusivo).
</ParamField>

<ParamField query="ending_before" type="string">
  ID do cliente que delimita o fim da página anterior (exclusivo).
</ParamField>

<ParamField query="email" type="string">
  Filtro por email (case-insensitive). Use o email exato.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X GET "https://api.chargefy.io/v1/customers?limit=20&starting_after=cus_123" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```

  ```bash Filter by email theme={}
  curl -X GET "https://api.chargefy.io/v1/customers?email=nome@email.com" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

## Resposta

`200 OK` com o envelope canônico de listagem.

| Campo      | Tipo      | Observação                                |
| ---------- | --------- | ----------------------------------------- |
| `object`   | `string`  | Sempre `"list"`                           |
| `data`     | `array`   | Cada item é um objeto `customer` completo |
| `has_more` | `boolean` | `true` quando há próxima página           |
| `url`      | `string`  | Path relativo (`/v1/customers`)           |

<ResponseExample>
  ```json 200 theme={}
  {
    "object": "list",
    "data": [
      {
        "id": "cus_123",
        "object": "customer",
        "billing_address": null,
        "billing_name": null,
        "created_at": "2026-05-16T14:09:27Z",
        "document": "12345678901",
        "document_type": "cpf",
        "email": "nome@email.com",
        "livemode": true,
        "metadata": {
          "reference_id": "ref_456"
        },
        "name": "Cliente Exemplo",
        "phone": null,
        "updated_at": null
      }
    ],
    "has_more": true,
    "url": "/v1/customers"
  }
  ```
</ResponseExample>