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.

​

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.

Show 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

cURL

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

​

Resposta de Exemplo

{
  "items": [
    {
      "id": "cus_abc123",
      "email": "[e-mail]",
      "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
  }
}