Atualizar um cliente

curl -X POST "https://api.chargefy.io/v1/customers/cus_d65x8mMGk6ZYdCJD" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {},
    "phone": "+5511999990000"
  }'

{
  "id": "cus_d65x8mMGk6ZYdCJD",
  "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": {},
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": "2026-05-16T15:02:10Z"
}

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

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

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.

object \| null

Objeto com { line1, line2, city, state, postal_code, country }.

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.

string \| null

Tipo do documento.

Valor	Descrição
`cpf`	Pessoa física.
`cnpj`	Pessoa jurídica.

string

Quando enviado, deve ser uma string não vazia.

object

Substitui completamente o metadata atual quando enviado.

string \| null

curl -X POST "https://api.chargefy.io/v1/customers/cus_d65x8mMGk6ZYdCJD" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {},
    "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_d65x8mMGk6ZYdCJD",
  "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": {},
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": "2026-05-16T15:02:10Z"
}

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

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.

curl -X POST "https://api.chargefy.io/v1/customers/cus_d65x8mMGk6ZYdCJD" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {},
    "phone": "+5511999990000"
  }'

{
  "id": "cus_d65x8mMGk6ZYdCJD",
  "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": {},
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": "2026-05-16T15:02:10Z"
}

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

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Atualizar um cliente

Autenticação

Parâmetros de caminho

Attributes

Resposta

Erros comuns

Webhook

​Autenticação

​Parâmetros de caminho

​Attributes

​Resposta

​Erros comuns

​Webhook

Autenticação

Parâmetros de caminho

Attributes

Resposta

Erros comuns

Webhook