Evento customer.deleted

Evento `customer.deleted`

Disparado quando um cliente é removido via DELETE /v1/customers/:id. data.object carrega o customer no estado imediatamente anterior à remoção. O cliente já não aparece em GET /v1/customers nem em GET /v1/customers/:id. Use este evento para remover o customer de listas ativas, encerrar sincronizações com CRM e preservar apenas o histórico necessário para conciliação de pagamentos anteriores.

Mesmo depois de removido, o cus_* pode continuar aparecendo em registros históricos de pagamentos, invoices ou assinaturas. Não reutilize o mesmo registro local como se ele ainda estivesse ativo.

Quando acontece

Situação	Como aparece no payload
Customer removido pela API	`type: "customer.deleted"` e `data.object.id` identifica o `cus_*`.
O customer saiu das consultas públicas	O objeto vem no webhook, mas não deve mais ser buscado por `GET`.
Dados finais precisam ser arquivados	`data.object` traz o último estado público conhecido.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (cus_*) para marcar o customer como removido no seu sistema.
Preserve referências históricas para conciliação, mas remova o customer de fluxos ativos.
Use o último estado em data.object para arquivar email, document e metadata antes de descartar dados locais.
Não tente buscar o customer por GET /v1/customers/:id depois de processar este evento.

Campos importantes

Campo	O que observar
`data.object.id`	Customer removido.
`email`	E-mail final conhecido do customer.
`document` / `document_type`	Dados fiscais finais conhecidos, quando presentes.
`metadata`	Valores livres usados para conciliação com seu sistema.
`updated_at`	Última atualização antes da remoção.
`organization`	Organização em que o customer existia.

Exemplo de payload

{
  "id": "evt_NNL3tE55mF4dQyCJ",
  "object": "event",
  "created_at": "2026-05-17T12:00:00Z",
  "data": {
    "object": {
      "id": "cus_171wXDVj7b371VEH",
      "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": "2026-05-16T15:02:10Z"
    }
  },
  "livemode": true,
  "organization": "org_3LQ4N24LC55v91WE",
  "request": {
    "id": null
  },
  "type": "customer.deleted"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento customer.deleted