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

# PATCH /api/v1/customers/:id

> Atualiza os dados de um cliente existente pelo seu ID

Atualiza parcialmente os campos de um cliente. Apenas os campos enviados serão modificados — campos omitidos permanecem inalterados. O campo `user_metadata` é mesclado com os metadados existentes (merge), não substituído.

## Autenticação

Requer **Organization Access Token (OAT)** via header `Authorization: Bearer`. Escopos necessários: `web:write` ou `customers:write`.

## Parâmetros de Caminho

**id** `string` *required*

ID único interno do cliente no Chargefy.

## Corpo da Requisição

Todos os campos são opcionais. Envie apenas os campos que deseja atualizar.

**name** `string`

Nome completo do cliente.

**billing\_name** `string`

Nome de cobrança (razão social ou nome completo para fins de nota fiscal).

**billing\_address** `object`

Endereço de cobrança do cliente. Substitui o endereço anterior por completo quando informado.

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

**country** `string`

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

**tax\_id** `object`

Documento fiscal do cliente (CPF ou CNPJ).

**user\_metadata** `object`

Metadados personalizados em formato chave-valor. São mesclados com os metadados já existentes — as chaves enviadas são inseridas ou atualizadas, as demais são preservadas.

**email\_verified** `boolean`

Define manualmente se o email do cliente está verificado. Útil em integrações onde a verificação ocorre externamente.

## Resposta

Retorna o objeto completo e atualizado do cliente.

**id** `string`

ID único do cliente.

**email** `string`

Email do cliente.

**name** `string`

Nome atualizado do cliente.

**billing\_name** `string`

Nome de cobrança (se informado).

**billing\_address** `object`

Endereço de cobrança atualizado (se informado).

**user\_metadata** `object`

Metadados mesclados após a atualização.

**organization\_id** `string`

ID da organização.

**created\_at** `string`

Data e hora de criação no formato ISO 8601.

**updated\_at** `string`

Data e hora da última atualização no formato ISO 8601.

## Exemplo

```bash cURL theme={null}
curl -X PATCH "https://api.chargefy.io/api/v1/customers/cus_def456" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Santos Junior",
    "billing_address": {
      "line1": "Rua Nova, 500",
      "city": "Campinas",
      "state": "SP",
      "postal_code": "13010-110",
      "country": "BR"
    },
    "user_metadata": {
      "plan": "enterprise",
      "upgraded_at": "2026-03-20"
    }
  }'
```

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

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

const customer = await chargefy.customers.update('cus_def456', {
  name: 'João Santos Junior',
  billing_address: {
    line1: 'Rua Nova, 500',
    city: 'Campinas',
    state: 'SP',
    postal_code: '13010-110',
    country: 'BR',
  },
  user_metadata: {
    plan: 'enterprise',
    upgraded_at: '2026-03-20',
  },
});
```

## Resposta de Exemplo

```json theme={null}
{
  "id": "cus_def456",
  "email": "joao@exemplo.com",
  "name": "João Santos Junior",
  "external_id": "user_001",
  "billing_name": "João Santos Junior",
  "billing_address": {
    "line1": "Rua Nova, 500",
    "city": "Campinas",
    "state": "SP",
    "postal_code": "13010-110",
    "country": "BR"
  },
  "user_metadata": {
    "source": "api",
    "plan": "enterprise",
    "upgraded_at": "2026-03-20"
  },
  "organization_id": "org_xyz",
  "created_at": "2026-03-12T10:00:00Z",
  "updated_at": "2026-03-20T09:00:00Z"
}
```


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