Listar 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: <id> apontando para uma organização conectada ativa.

Parâmetros de query

integer

padrão:"10"

Quantidade de itens por página. Entre 1 e 100.

string

ID do cliente que delimita o início da próxima página (exclusivo).

string

ID do cliente que delimita o fim da página anterior (exclusivo).

string

Filtro por email (case-insensitive). Use o email exato.

string

CPF ou CNPJ exato. Máscaras são normalizadas para somente dígitos; o valor deve conter 11 ou 14 dígitos. A busca considera somente clientes ativos da organização e do ambiente autenticados. Quando combinado com email, ambos os filtros devem corresponder ao mesmo cliente.

curl -X GET "https://api.chargefy.io/v1/customers?limit=20&starting_after=cus_QeCoiM7iiFx52MpB" \
  -H "Authorization: Bearer {{API_KEY}}"

curl -X GET "https://api.chargefy.io/v1/[email protected]" \
  -H "Authorization: Bearer {{API_KEY}}"

curl -X GET "https://api.chargefy.io/v1/customers?document=11144477735&limit=1" \
  -H "Authorization: Bearer {{API_KEY}}"

Reutilizar um comprador

Antes de criar um cliente, consulte o documento. Uma lista vazia permite seguir com a criação. Se outra requisição criar o mesmo documento simultaneamente, POST /v1/customers retorna 409 customer_document_exists: consulte novamente por document e reutilize o cliente encontrado. Não use o email como identidade única e não sobrescreva dados cadastrais apenas porque uma compra chegou com outro email. O filtro não autoriza uma compra nem permite recuperar cartões no navegador; a chave secreta e a associação com o pedido continuam no servidor. Um filtro document vazio ou com quantidade de dígitos inválida retorna 400 com param: "document"; ele nunca é ignorado para retornar a lista completa.

Resposta

200 OK com o payload 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`)

200

{
  "object": "list",
  "data": [
    {
      "id": "cus_QeCoiM7iiFx52MpB",
      "object": "customer",
      "billing_address": null,
      "billing_name": null,
      "created_at": "2026-05-16T14:09:27Z",
      "document": "12345678901",
      "document_type": "cpf",
      "email": "[email protected]",
      "livemode": true,
      "metadata": {},
      "name": "Cliente Exemplo",
      "phone": null,
      "trade_name": null,
      "updated_at": null
    }
  ],
  "has_more": true,
  "url": "/v1/customers"
}

Erros comuns

400

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "type": "invalid_request_error"
  }
}

401

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided: ch_live_***************************************9f2c",
    "type": "authentication_error"
  }
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Autenticação

Parâmetros de query

Reutilizar um comprador

Resposta

Erros comuns

​Autenticação

​Parâmetros de query

​Reutilizar um comprador

​Resposta

​Erros comuns

Autenticação

Parâmetros de query

Reutilizar um comprador

Resposta

Erros comuns