Skip to main content
Atualiza parcialmente os campos de um cliente identificado pelo external_id do seu sistema. Equivalente ao endpoint PATCH /api/v1/customers/:id, mas utiliza o ID externo como chave de busca. Apenas os campos enviados serão modificados. O campo user_metadata é mesclado com os metadados existentes (merge).

​
Autenticação

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

​
Parâmetros de Caminho

​
external_id
string
required
Identificador externo único do cliente dentro da organização, conforme definido na criação ou atualização anterior.

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

​
Resposta

Retorna o objeto completo e atualizado do cliente.
​
id
string
ID único interno do cliente no Chargefy.
​
email
string
Email do cliente.
​
name
string
Nome atualizado do cliente.
​
external_id
string
ID externo 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

curl -X PATCH "https://api.chargefy.io/api/v1/customers/external/user_001" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Santos Junior",
    "user_metadata": {
      "plan": "enterprise",
      "upgraded_at": "2026-03-20"
    }
  }'

​
Resposta de Exemplo

{
  "id": "cus_def456",
  "email": "[email protected]",
  "name": "João Santos Junior",
  "external_id": "user_001",
  "billing_name": "João Santos Junior",
  "billing_address": {
    "line1": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "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"
}