> ## 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.

# POST /api/v1/customers

> Cria um novo cliente na organização

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](https://scaleup-c34c4386.mintlify.site/guides/parent-marketplace-suborganizations.md).

## 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.

**Campos**

**line1** `string`

Logradouro e número.

**line2** `string`

Complemento (apto, sala, etc.).

**city** `string`

Cidade.

**state** `string`

Estado (UF, ex: `SP`).

**postal\_code** `string`

CEP (apenas dígitos ou com hífen).

**country** `string`

País no formato ISO 3166-1 alpha-2 (ex: `BR`).

**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

```bash cURL theme={null}
curl -X POST https://api.chargefy.io/api/v1/customers \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@exemplo.com",
    "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"
    }
  }'
```

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

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

const customer = await chargefy.customers.create({
  email: 'joao@exemplo.com',
  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

```json theme={null}
{
  "id": "cus_def456",
  "email": "joao@exemplo.com",
  "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"
}
```


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