Skip to main content
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.

​
Exemplo

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": "[email protected]",
      "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
  }
}