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

# Clientes

> Objeto customer: campos, relacionamentos e eventos.

Um `customer` é o cadastro de um cliente na conta: contato, identificação, preferências de email e indicadores de receita. O vínculo com pedidos usa o ID do cliente. Criar um cliente não cria um pedido nem concede acesso a conteúdo.

## Objeto completo

Formato retornado pelas consultas e pelos itens das listagens. Os campos de retorno não são todos editáveis; confira as regras de escrita abaixo.

```json theme={null}
{
  "id": "cus_1234567890abcdef",
  "city": null,
  "country": null,
  "created_at": "2030-01-01T00:00:00.000Z",
  "currency": "BRL",
  "document": null,
  "document_type": null,
  "email": "cliente@example.com",
  "email_marketing_status": "subscribed",
  "external_id": null,
  "first_name": null,
  "last_name": null,
  "metadata": {},
  "mrr_cents": 0,
  "name": "Cliente Exemplo",
  "object": "customer",
  "phone": null,
  "region": null,
  "total_revenue_cents": 0,
  "updated_at": "2030-01-01T00:00:00.000Z"
}
```

## Campos do objeto

**id** `string`

Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes.

**city** `string | null`

Cidade do cliente; null quando ausente.

**country** `string | null`

País informado no cadastro; null quando ausente.

**created\_at** `string`

Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura.

**currency** `string | null`

Moeda dos indicadores do cliente. Pode ser null. Somente leitura.

**document** `string | null`

Documento do cliente como string, preservando zeros à esquerda; null quando ausente.

**document\_type** `string | null`

Tipo do documento informado, como cpf ou cnpj; null quando ausente.

**email** `string | null`

Email do cliente. Obrigatório e não vazio na criação; convertido para minúsculas ao criar.

**email\_marketing\_status** `string | null`

Situação de email marketing: subscribed, unsubscribed, archived, requires\_verification, invalid\_email ou bounced.

**external\_id** `string | null`

Identificador do cliente no seu sistema. Pode ser null. Não substitui o id da Hubfy.

**first\_name** `string | null`

Primeiro nome; null quando ausente.

**last\_name** `string | null`

Sobrenome; null quando ausente.

**metadata** `object`

Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use `{}` para limpar. Não aceita null.

**mrr\_cents** `integer`

Receita recorrente mensal registrada para o cliente, em centavos. Somente leitura.

**name** `string | null`

Nome do cliente. Obrigatório e não vazio na criação.

**object** `string`

Tipo do objeto retornado. O valor é fixo para este recurso.

Sempre `customer`.

**phone** `string | null`

Telefone do cliente como string; null quando ausente.

**region** `string | null`

Estado ou região do cliente; null quando ausente.

**total\_revenue\_cents** `integer`

Receita acumulada registrada para o cliente, em centavos. Não deve ser enviada em criação ou atualização.

**updated\_at** `string`

Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura.

## Criação e alterações

Na criação, envie `email` e `name`, ambos não vazios. O email é convertido para minúsculas. Se já existir um cliente com esse email na conta, a criação retorna esse cadastro e preenche somente valores ausentes; não sobrescreve os dados existentes. Para alterar valores preenchidos, use a atualização.

A atualização aceita os dados de contato, identificação, preferências, `external_id` e `metadata`. Os indicadores financeiros e `currency` são somente leitura. Excluir um cliente não é uma operação de estorno ou cancelamento; vínculos que impeçam a remoção retornam erro.

Campos omitidos em uma atualização são preservados. `metadata` substitui o objeto inteiro quando enviado. Campos desconhecidos são rejeitados.

## Relacionamentos

[Pedidos](https://docs.hubfy.io/api-reference/orders/object.md) apontam para este cadastro pelo campo `customer`. Use `GET /v1/orders?customer=cus_1234567890abcdef` para listar os pedidos associados.

## Eventos

Clientes não possuem eventos públicos próprios. Para mudanças nos pedidos do cliente, receba `order.updated` e confira o campo `customer` do pedido.

Eventos descrevem mudanças efetivas no objeto público. Repetir uma operação sem alterar o objeto não garante um evento. Confira [entrega e assinatura](https://docs.hubfy.io/api-reference/webhooks/delivery.md).


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