> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moneydev.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar um cliente

> Cria um registro de cliente reutilizável que você pode vincular a sessões de checkout.

<Info>
  `POST /v1/customers`  ·  Requer o escopo `customers:write`
</Info>

Cria um cliente na sua conta. Vincule um a um [checkout](/api-reference/checkouts/create) via `customer_id` para não reenviar os dados do comprador a cada vez.

## Parâmetros do corpo

<ParamField body="name" type="string" required>
  Nome completo do cliente ou razão social. De 1 a 160 caracteres.
</ParamField>

<ParamField body="email" type="string" required>
  E-mail válido, até 320 caracteres. Armazenado em minúsculas. Deve ser único na sua conta.
</ParamField>

<ParamField body="phone" type="string">
  Telefone, de 1 a 32 caracteres. Recomenda-se o formato E.164 (`+5511999999999`).
</ParamField>

<ParamField body="tax_id" type="string">
  CPF ou CNPJ, de 1 a 32 caracteres. Enviado como veio — só dígitos ou formatado.
</ParamField>

<ParamField body="metadata" type="object">
  Pares chave–valor livres para seu uso. Retornados em toda representação do cliente.
</ParamField>

Campos desconhecidos causam `400` (`invalid_request`).

## Requisição

```bash cURL theme={null}
curl --request POST https://api.moneydev.com.br/v1/customers \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "João da Silva",
    "email": "joao.silva@example.com",
    "phone": "+5511999999999",
    "tax_id": "12345678909",
    "metadata": { "user_id": "usr_789" }
  }'
```

## Resposta

`201 Created` com o [objeto de cliente](#objeto-de-cliente).

```json theme={null}
{
  "id": "cus_9b2c4f1a-3d5e-4a7b-8c9d-1e2f3a4b5c6d",
  "object": "customer",
  "name": "João da Silva",
  "email": "joao.silva@example.com",
  "phone": "+5511999999999",
  "tax_id": "12345678909",
  "status": "active",
  "metadata": { "user_id": "usr_789" },
  "created_at": "2026-08-28T13:00:00.000Z",
  "updated_at": "2026-08-28T13:00:00.000Z"
}
```

## Erros

| Status | `code` | Causa |
| - | - | - |
| `400` | `invalid_request` | Validação falhou; `param` indica o campo |
| `400` | `invalid_customer_name` | `name` ficou vazio após remover espaços |
| `409` | `customer_email_already_exists` | Outro cliente da sua conta usa esse e-mail |

## Objeto de cliente

<ResponseField name="id" type="string">ID do cliente, com prefixo `cus_`.</ResponseField>
<ResponseField name="object" type="string">Sempre `"customer"`.</ResponseField>
<ResponseField name="name" type="string">Nome completo ou razão social.</ResponseField>
<ResponseField name="email" type="string">E-mail, em minúsculas.</ResponseField>
<ResponseField name="phone" type="string | null">Telefone, ou `null`.</ResponseField>
<ResponseField name="tax_id" type="string | null">CPF ou CNPJ, ou `null`.</ResponseField>
<ResponseField name="status" type="string">`active` ou `inactive`. Novos clientes nascem `active`.</ResponseField>
<ResponseField name="metadata" type="object">Seus metadados. `{}` se nada foi definido.</ResponseField>
<ResponseField name="created_at" type="string">Data/hora de criação em ISO 8601.</ResponseField>
<ResponseField name="updated_at" type="string">Data/hora da última alteração em ISO 8601.</ResponseField>


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