Skip to main content
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"
  }'

{
  "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"
}
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

​
id
string
required
ID do cliente (cus_*).

​
Attributes

Todos os campos são opcionais. Mesmo set aceito em POST /v1/customers exceto que email aqui não pode ser vazio quando enviado.
​
billing_address
object \| null
Objeto com { line1, line2, city, state, postal_code, country }.
​
billing_name
string \| null
​
document
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.
​
document_type
string \| null
cpf ou cnpj.
​
email
string
Quando enviado, deve ser uma string não vazia.
​
metadata
object
Substitui completamente o metadata atual quando enviado.
​
name
string \| null
​
phone
string \| null
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"
  }'

​
Resposta

200 OK com o objeto customer completo (mesmo shape de GET /v1/customers/:id). A resposta direta não carrega diff; quem precisa de diff lê o webhook customer.updated. 
{
  "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"
}

​
Erros comuns

StatuscodeQuando ocorre
400invalid_request_erroremail enviado vazio; metadata não-objeto
404resource_missingCliente não existe nesta organização
409customer_document_lockeddocument/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.