Evento product.updated

Evento `product.updated`

Disparado quando um produto muda via POST /v1/products/:id ou quando DELETE /v1/products/:id cai no caminho de desativação. Use este evento para manter o catálogo local alinhado depois de mudanças em nome, descrição, imagem, recursos de marketing, preço padrão, metadata ou estado ativo do produto. data.object carrega o product completo no estado atual. data.previous_attributes traz só os campos que mudaram, com os valores anteriores.

O estado final está sempre em data.object. Use data.previous_attributes para auditoria, logs e notificações condicionais, não como substituto do objeto atual.

Quando acontece

Situação	Como aparece no payload
Produto editado	`data.object` vem com o produto atualizado e `previous_attributes` lista os campos alterados.
Preço padrão trocado ou limpo	`data.object.default_price` mostra o valor atual; o valor anterior aparece em `previous_attributes.default_price`.
Produto desativado	`data.object.is_active: false` e `previous_attributes.is_active: true`.
Produto reativado	`data.object.is_active: true` e `previous_attributes.is_active: false`.
Metadata substituída	`previous_attributes.metadata` mostra o objeto anterior.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (prod_*) como chave do produto no seu sistema.
Atualize o registro local usando o data.object completo.
Use data.previous_attributes para saber exatamente o que mudou e gerar auditoria.
Quando is_active virar false, remova o produto de novas ofertas sem apagar histórico já conciliado.
Quando default_price mudar, aplique o novo preço padrão apenas em fluxos futuros.
Continue acompanhando preços pelo ciclo de eventos price.*; prices[] no produto é uma visão do catálogo no momento do evento.

Campos importantes

Campo	O que observar
`data.object.is_active`	Define se o produto deve aparecer em novas vendas e assinaturas.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`default_price`	Preço padrão atual do produto.
`prices`	Lista de preços associada ao produto no payload atual. Pode vir vazia.
`marketing_features`	Lista atual de recursos comerciais exibidos ao comprador.
`metadata`	Metadata atual do produto; quando muda, o valor anterior fica no diff.
`updated_at`	Momento da alteração.

Variações de catálogo e desativação

Variação	O que muda
Edição de catálogo	Campos como `name`, `description`, `image_url`, `marketing_features`, `is_tax_applicable` e `metadata` mudam por merge.
Troca de preço padrão	`default_price` passa a apontar para outro preço do mesmo produto, ou para `null`.
Desativação segura	Um `DELETE` pode virar `is_active=false` quando o produto precisa permanecer auditável. Esse caminho emite `product.updated`.
Remoção real	Quando o produto pôde ser removido de verdade, a resposta direta do delete confirma `{ deleted: true }`; este evento cobre o caminho de atualização/desativação.

Exemplo de payload

{
  "id": "evt_ZeEPxMaMybkPaZMw",
  "object": "event",
  "created_at": "2026-05-16T15:02:10Z",
  "data": {
    "object": {
      "id": "prod_ZHcLg9MdDyq626P4",
      "object": "product",
      "created_at": "2026-05-16T14:09:27Z",
      "default_price": "price_L3p98eJqp2jPShh7",
      "description": "Acesso completo",
      "image_url": null,
      "is_active": false,
      "is_tax_applicable": true,
      "livemode": true,
      "marketing_features": [
        {
          "name": "Acesso ilimitado"
        }
      ],
      "metadata": {},
      "name": "Plano Pro",
      "prices": [],
      "updated_at": "2026-05-16T15:02:10Z"
    },
    "previous_attributes": {
      "is_active": true
    }
  },
  "livemode": true,
  "organization": "org_FwkKNCJiLEVARt48",
  "request": {
    "id": null
  },
  "type": "product.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento product.updated