Skip to main content
Um customer representa a pessoa física ou jurídica que compra de você. Ele reúne num só lugar a identidade e os dados de cobrança do comprador — nome, e-mail, telefone, CPF/CNPJ, nome de cobrança e endereço — e usa o e-mail como chave única dentro da organização, de modo que o mesmo comprador continua sendo o mesmo customer por mais checkouts que ele faça. É a ele que se prendem os pagamentos, as assinaturas, as invoices e os métodos de pagamento salvos: o customer é o fio que liga todo o histórico financeiro de uma pessoa. Ele surge tanto quando você o cria pela API quanto quando um checkout hospedado o resolve a partir dos dados que o comprador preenche — e, uma vez criado, é reaproveitado nas cobranças seguintes em vez de gerar um cadastro duplicado.

​
Data Object

Este é o formato completo retornado em create, get, update, itens de list e em data.object dos webhooks customer.*. 
{
  "id": "cus_123",
  "object": "customer",
  "billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Rua Exemplo, 100",
    "line2": null,
    "postal_code": "01000-000",
    "state": "SP"
  },
  "billing_name": "Cliente",
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678901",
  "document_type": "cpf",
  "email": "nome@email.com",
  "livemode": true,
  "metadata": {
    "reference_id": "id_456"
  },
  "name": "Cliente",
  "phone": "+5511999990000",
  "updated_at": "2026-05-16T15:02:10Z"
}
​
id
string
Identificador do customer. Usa o prefixo cus_*.
​
object
string
Sempre "customer".
​
billing_address
object | null
Endereço de cobrança. Vem null quando não foi informado.
​
billing_name
string | null
Nome ou razão social usada em cobrança. Vem null quando não foi informado.
​
created_at
string
Data de criação em ISO 8601.
​
document
string | null
CPF ou CNPJ do cliente, apenas dígitos. Vem null quando não foi informado.
​
document_type
string | null
Tipo do documento: cpf, cnpj ou null.
​
email
string
Email do cliente. É único dentro da organização atuante.
​
livemode
boolean
true em produção; false em ambiente de teste.
​
metadata
object
Objeto livre para correlacionar o customer com o seu sistema. Quando vazio, retorna {}.
​
name
string | null
Nome do cliente. Vem null quando não foi informado.
​
phone
string | null
Telefone do cliente. Vem null quando não foi informado.
​
updated_at
string | null
Data da última atualização em ISO 8601. Vem null enquanto o customer nunca foi atualizado.

​
Operações

​
Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook: O payload sempre carrega o objeto customer completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.