Skip to main content
Cria um novo registro de cliente. O email deve ser único dentro da organização. Clientes também podem ser criados automaticamente durante o checkout quando um novo email é informado. Se um comprador já existir no gateway de pagamentos com o mesmo CPF/CNPJ, a API retorna 200 com status: "zoop_buyer_exists" antes de prosseguir. Reenvie a requisição com confirm_import: true para confirmar a importação.

​
Autenticação

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

​
Organização pai (marketplace)

Com OAT da organização pai, você pode criar o cliente na sub-organização enviando organization_id com o UUID do filho. A API valida que existe relação direta pai→filho em organization_relationships. Se você omitir organization_id, o cliente é criado na organização do token (a pai). Exemplos em Marketplace: OAT da organização pai e sub-organizações.

​
Corpo da Requisição

​
organization_id
string
Sessão de usuário: obrigatório para definir a org do cliente.OAT da própria org: opcional — padrão é a org do token.OAT da org pai: use para criar cliente em uma sub-organização (valor = UUID do filho).
​
email
string
required
Endereço de email do cliente. Deve ser único dentro da organização.
​
name
string
Nome completo do cliente.
​
phone
string
Número de telefone do cliente (incluindo DDD).
​
taxpayer_id
string
CPF ou CNPJ do cliente, sem formatação (apenas dígitos). Também aceito como tax_id.
​
birthdate
string
Data de nascimento no formato YYYY-MM-DD.
​
billing_name
string
Nome de cobrança (razão social ou nome completo para fins de emissão de nota fiscal).
​
billing_address
object
Endereço de cobrança do cliente.
​
tax_id
object
Objeto alternativo para informar o documento fiscal do cliente.
​
external_id
string
Identificador único do cliente no seu próprio sistema. Deve ser único por organização. Permite buscar e atualizar o cliente via /external/:external_id.
​
user_metadata
object
Metadados personalizados em formato chave-valor livre. Útil para armazenar informações adicionais do seu sistema.
​
confirm_import
boolean
Quando true, confirma a importação do cliente mesmo que um comprador com o mesmo CPF/CNPJ já exista no gateway. Utilize após receber a resposta zoop_buyer_exists.

​
Resposta

Retorna 201 Created com o objeto do cliente criado. Se um comprador com o mesmo CPF/CNPJ já existir no gateway, retorna 200 com status: "zoop_buyer_exists" e os dados do comprador para confirmação. Reenvie a requisição com confirm_import: true para prosseguir com a criação. Se o email já estiver em uso na organização, retorna 409 Conflict.
​
id
string
ID único do cliente no Chargefy.
​
email
string
Email do cliente.
​
name
string
Nome do cliente.
​
external_id
string
ID externo associado (se informado).
​
organization_id
string
ID da organização à qual o cliente pertence.
​
created_at
string
Data e hora de criação no formato ISO 8601.

​
Exemplo

curl -X POST https://api.chargefy.io/api/v1/customers \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "João Santos",
    "taxpayer_id": "12345678901",
    "phone": "11999990000",
    "external_id": "user_001",
    "billing_address": {
      "line1": "Av. Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR"
    },
    "user_metadata": {
      "source": "api",
      "plan": "pro"
    }
  }'

​
Resposta de Exemplo

{
  "id": "cus_def456",
  "email": "[email protected]",
  "name": "João Santos",
  "external_id": "user_001",
  "organization_id": "org_xyz",
  "taxpayer_id": "12345678901",
  "billing_address": {
    "line1": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR"
  },
  "user_metadata": {
    "source": "api",
    "plan": "pro"
  },
  "created_at": "2026-03-12T10:00:00Z",
  "updated_at": "2026-03-12T10:00:00Z"
}