> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/v1/customers

> Retorna uma lista paginada de clientes da organização

Lista clientes com paginação, filtro por email e busca por nome ou email.

Com **OAT da organização pai**: se você **omitir** `organization_id`, a lista inclui clientes da **sua organização** e de **todas as sub-organizações diretas**. Se informar `organization_id`, deve ser a sua org ou um filho direto (senão `403`). Com **token de usuário**, o comportamento de filtro por `organization_id` continua como antes.

Guia com exemplos: [Marketplace: OAT da organização pai e sub-organizações](https://scaleup-c34c4386.mintlify.site/guides/parent-marketplace-suborganizations.md).

## Autenticação

Requer **Organization Access Token (OAT)** via header `Authorization: Bearer`. Escopos necessários: `web:read`, `web:write`, `customers:read` ou `customers:write`.

## Parâmetros de Query

**organization\_id** `string[]`

**OAT:** opcional para agregar pai + filhos; quando presente, restringe às orgs indicadas (cada uma deve ser o próprio token ou sub-org direta).

**Usuário (sessão):** pode ser usado para filtrar por uma ou mais organizações (membro).

**email** `string`

Filtra clientes pelo endereço de email (correspondência exata, sem distinção de maiúsculas/minúsculas).

**query** `string`

Busca textual por nome ou email do cliente (busca parcial).

**limit** `integer` (default: 20)

Número máximo de itens retornados por página.

**page** `integer` (default: 1)

Número da página desejada (base 1). Use em conjunto com `limit` para paginar os resultados.

## Resposta

**items** `Customer[]`

Lista de objetos de cliente que correspondem aos filtros aplicados.

**pagination** `object`

Informações de paginação do resultado.

**Propriedades**

**total\_count** `integer`

Número total de clientes que correspondem à consulta.

**max\_page** `integer`

Número total de páginas disponíveis com base no `limit` informado.

## Exemplo

```bash cURL theme={null}
curl -X GET "https://api.chargefy.io/api/v1/customers?page=1&limit=20&query=maria" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const result = await chargefy.customers.list({
  page: 1,
  limit: 20,
  query: 'maria',
});
```

## Resposta de Exemplo

```json theme={null}
{
  "items": [
    {
      "id": "cus_abc123",
      "email": "maria@exemplo.com",
      "name": "Maria Silva",
      "external_id": "user_maria",
      "organization_id": "org_xyz",
      "taxpayer_id": "12345678901",
      "billing_address": {
        "line1": "Rua das Flores, 100",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01310-100",
        "country": "BR"
      },
      "user_metadata": {},
      "created_at": "2026-02-15T08:30:00Z",
      "updated_at": "2026-03-10T14:00:00Z"
    }
  ],
  "pagination": {
    "total_count": 1,
    "max_page": 1
  }
}
```


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