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

# Overview

> O objeto Customer

Um `customer` representa a pessoa física ou jurídica que compra de você. Ele reúne num só lugar a identidade e os dados de cobrança do comprador — nome, e-mail, telefone, CPF/CNPJ, nome de cobrança e endereço — e usa o e-mail como chave única dentro da organização, de modo que o mesmo comprador continua sendo o mesmo `customer` por mais checkouts que ele faça.

É a ele que se prendem os pagamentos, as assinaturas, as invoices e os métodos de pagamento salvos: o `customer` é o fio que liga todo o histórico financeiro de uma pessoa. Ele surge tanto quando você o cria pela API quanto quando um checkout hospedado o resolve a partir dos dados que o comprador preenche — e, uma vez criado, é reaproveitado nas cobranças seguintes em vez de gerar um cadastro duplicado.

## Data Object

Este é o formato completo retornado em `create`, `get`, `update`, itens de
`list` e em `data.object` dos webhooks `customer.*`.

```json theme={}
{
  "id": "cus_123",
  "object": "customer",
  "billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Rua Exemplo, 100",
    "line2": null,
    "postal_code": "01000-000",
    "state": "SP"
  },
  "billing_name": "Cliente",
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678901",
  "document_type": "cpf",
  "email": "nome@email.com",
  "livemode": true,
  "metadata": {
    "reference_id": "id_456"
  },
  "name": "Cliente",
  "phone": "+5511999990000",
  "updated_at": "2026-05-16T15:02:10Z"
}
```

<ResponseField name="id" type="string">
  Identificador do customer. Usa o prefixo `cus_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"customer"`.
</ResponseField>

<ResponseField name="billing_address" type="object | null">
  Endereço de cobrança. Vem `null` quando não foi informado.

  <Expandable title="Campos de billing_address">
    <ResponseField name="line1" type="string | null">
      Rua, número e complemento principal.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      Complemento opcional.
    </ResponseField>

    <ResponseField name="city" type="string | null">
      Cidade.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      Estado ou província.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      CEP ou código postal.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      País em código ISO de 2 letras, como `BR`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="billing_name" type="string | null">
  Nome ou razão social usada em cobrança. Vem `null` quando não foi informado.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="document" type="string | null">
  CPF ou CNPJ do cliente, apenas dígitos. Vem `null` quando não foi informado.
</ResponseField>

<ResponseField name="document_type" type="string | null">
  Tipo do documento: `cpf`, `cnpj` ou `null`.
</ResponseField>

<ResponseField name="email" type="string">
  Email do cliente. É único dentro da organização atuante.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Objeto livre para correlacionar o customer com o seu sistema. Quando vazio,
  retorna `{}`.
</ResponseField>

<ResponseField name="name" type="string | null">
  Nome do cliente. Vem `null` quando não foi informado.
</ResponseField>

<ResponseField name="phone" type="string | null">
  Telefone do cliente. Vem `null` quando não foi informado.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601. Vem `null` enquanto o customer nunca
  foi atualizado.
</ResponseField>

## Operações

* [Listar customers](/api-reference/customers/list)
* [Criar customer](/api-reference/customers/create)
* [Consultar customer](/api-reference/customers/get)
* [Atualizar customer](/api-reference/customers/update)
* [Remover customer](/api-reference/customers/delete)

## Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

* [`customer.created`](/api-reference/webhooks/customer.created)
* [`customer.updated`](/api-reference/webhooks/customer.updated)
* [`customer.deleted`](/api-reference/webhooks/customer.deleted)

O payload sempre carrega o objeto `customer` completo em `data.object`; eventos de update também incluem `data.previous_attributes` com os valores anteriores dos campos alterados.