Evento customer.created

Evento `customer.created`

Disparado quando um cliente é criado via POST /v1/customers ou indiretamente durante checkout e cobranças automáticas. Use este evento para criar ou reconciliar o comprador no seu CRM, ERP ou camada de assinaturas. data.object usa o mesmo shape do objeto customer. Use data.object.id como identidade do cadastro. O e-mail é obrigatório, mas não é único: mais de um customer da mesma organização pode usar o mesmo endereço.

Este evento confirma a criação do cadastro do comprador. Ele não significa, por si só, que um pagamento foi aprovado ou que uma assinatura ficou ativa.

Quando acontece

Situação	Como aparece no payload
Customer criado pela API	`data.object.id` traz o novo `cus_*`.
Checkout resolve um comprador novo	O customer completo aparece em `data.object`.
Dados fiscais foram enviados	`document` e `document_type` vêm preenchidos.
Metadata foi enviada na criação	`metadata` ecoa os pares informados.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (cus_*) como chave do comprador no seu sistema.
Faça upsert pelo id público e use email para conciliação humana ou deduplicação local.
Salve document, document_type, billing_name e billing_address quando seu fluxo precisar de dados fiscais ou de cobrança.
Use metadata para correlacionar o customer com o identificador interno que você enviou.

Campos importantes

Campo	O que observar
`data.object.id`	Identificador público do customer.
`email`	E-mail do customer. Obrigatório, mas não único dentro da organização.
`document` / `document_type`	CPF ou CNPJ do comprador, quando informado.
`billing_name` / `billing_address`	Dados de cobrança disponíveis para notas, recibos ou conciliação.
`phone`	Telefone do comprador, quando informado.
`metadata`	Objeto livre para correlacionar com seu sistema.
`updated_at`	Vem `null` enquanto o customer ainda não foi atualizado depois da criação.

Exemplo de payload

{
  "id": "evt_3T1XsMDby86NzyAj",
  "object": "event",
  "created_at": "2026-05-16T14:09:27Z",
  "data": {
    "object": {
      "id": "cus_h4mCc1HWGqLFtiMU",
      "object": "customer",
      "billing_address": null,
      "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": null,
      "updated_at": null
    }
  },
  "livemode": true,
  "organization": "org_1Y2hU49c1Bsb9DzB",
  "request": {
    "id": null
  },
  "type": "customer.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento customer.created