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.

Show 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

cURL

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

​

Resposta de Exemplo

{
  "id": "cus_def456",
  "email": "[e-mail]",
  "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"
}