Pular para o conteúdo principal
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
obrigatório
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
Endereço de cobrança. Aceita endereços brasileiros e internacionais, sem exigir formato específico de estado ou código postal. Letras e traços do código postal são preservados.Para novos cadastros, prefira country em duas letras, como BR, US, IE ou PT. Nos Estados Unidos, você pode usar a sigla do estado, como FL, e ZIP ou ZIP+4, como 33064-2845. Esses formatos são opcionais: integrações existentes podem continuar enviando o endereço como hoje.Além de line1, line2, city, state, postal_code e country, você pode enviar street, number, complement e neighborhood. Omita billing_address para preservar o endereço atual. Envie null para apagar. Ao enviar um objeto, envie o endereço inteiro: ele substitui o anterior.
string \| null
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.
string
Quando enviado, deve ser uma string não vazia.
object
Substitui completamente o metadata atual quando enviado.
string \| null
string \| null
Gravado no formato internacional (+5511999990000); número sem + é lido como brasileiro. Envie null para limpar.
string \| null
Nome fantasia do cliente (apelido, em pessoa física). Campo de exibição — não aparece em documento fiscal. Envie null para limpar.

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.

Erros comuns

Webhook

A atualização dispara customer.updated com o customer completo em data.object e o diff em data.previous_attributes.