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

# Update a Customer

> Atualiza um cliente.

Atualiza campos de um `customer`. Semântica é **merge**: campos ausentes ficam
como estão; envie `null` (ou `""` quando o schema aceitar) para limpar.
`metadata`, quando enviado, substitui o objeto inteiro.

## Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o
header `Organization: <organization_id>` apontando para uma organização
conectada ativa.

## Parâmetros de caminho

<ParamField path="id" type="string" required>
  ID do cliente (`cus_*`).
</ParamField>

## Attributes

Todos os campos são opcionais. Mesmo set aceito em
[`POST /v1/customers`](/api-reference/customers/create#body) exceto que
`email` aqui não pode ser vazio quando enviado.

<ParamField body="billing_address" type="object \| null">
  Objeto com `{ line1, line2, city, state, postal_code, country }`.
</ParamField>

<ParamField body="billing_name" type="string \| null" />

<ParamField body="document" type="string \| null">
  CPF/CNPJ. Editável apenas enquanto o cliente ainda não foi usado em uma
  cobrança; depois disso fica imutável e a alteração retorna
  `409 customer_document_locked`.
</ParamField>

<ParamField body="document_type" type="string \| null">
  `cpf` ou `cnpj`.
</ParamField>

<ParamField body="email" type="string">
  Quando enviado, deve ser uma string não vazia.
</ParamField>

<ParamField body="metadata" type="object">
  Substitui completamente o `metadata` atual quando enviado.
</ParamField>

<ParamField body="name" type="string \| null" />

<ParamField body="phone" type="string \| null" />

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/customers/cus_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {
        "reference_id": "ord_789"
      },
      "phone": "+5511999990000"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `customer` completo (mesmo shape de
[`GET /v1/customers/:id`](/api-reference/customers/get#resposta)). A resposta
direta **não** carrega diff; quem precisa de diff lê o webhook
[`customer.updated`](/api-reference/webhooks/customer.updated).

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

  ```json 409 theme={}
  {
    "error": {
      "code": "customer_document_locked",
      "message": "Customer document can't be changed after the customer has been used for a payment.",
      "param": "document",
      "type": "invalid_request_error"
    }
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`                     | Quando ocorre                                                                         |
| ------ | -------------------------- | ------------------------------------------------------------------------------------- |
| `400`  | `invalid_request_error`    | `email` enviado vazio; `metadata` não-objeto                                          |
| `404`  | `resource_missing`         | Cliente não existe nesta organização                                                  |
| `409`  | `customer_document_locked` | `document`/`document_type` alterado depois que o cliente já foi usado em uma cobrança |

## Webhook

A atualização dispara `customer.updated` com o `customer` completo em
`data.object` e o diff em `data.previous_attributes`.