Evento price.updated

Evento `price.updated`

Disparado quando um preço muda via POST /v1/prices/:id ou quando DELETE /v1/prices/:id cai no caminho de desativação. Use este evento para refletir mudanças nos campos editáveis de um preço, como name, metadata, tax_behavior e is_active. Campos de valor e cadência não mudam depois da criação; para trocar valor, crie um novo price. data.object carrega o price completo no estado atual. data.previous_attributes traz só os campos que mudaram, com os valores anteriores.

O estado final está em data.object. O diff em data.previous_attributes mostra o que mudou, mas não substitui o objeto completo.

Quando acontece

Situação	Como aparece no payload
Preço editado	`data.object` vem atualizado e `previous_attributes` lista os campos alterados.
Preço desativado por update	`data.object.is_active: false` e `previous_attributes.is_active: true`.
Preço desativado por delete seguro	Mesmo shape de desativação: `is_active` muda para `false`.
Preço 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 (price_*) como chave do preço no seu sistema.
Atualize o preço local usando o data.object completo.
Use data.previous_attributes para auditoria e notificações condicionais.
Quando is_active virar false, pare de oferecer o preço em novos checkouts e assinaturas.
Preserve cobranças e assinaturas já criadas com esse preço; elas continuam apontando para o price_* original.
Para trocar valor, espere um novo price.created e trate este price.updated como desativação ou ajuste de catálogo.

Campos importantes

Campo	O que observar
`data.object.is_active`	Define se o preço ainda pode ser usado em novos fluxos.
`data.previous_attributes`	Valores anteriores dos campos públicos que mudaram.
`product`	Produto ao qual o preço pertence.
`unit_amount` / `currency`	Termos fixos do preço; não mudam por update.
`type` / `recurring`	Forma de cobrança e cadência fixadas na criação.
`tax_behavior`	Campo editável que pode mudar a configuração fiscal futura.
`metadata`	Metadata atual do preço; 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 simples	Campos como `name`, `metadata` ou `tax_behavior` mudam, e o diff mostra os valores anteriores.
Arquivamento do preço	`is_active=false` tira o preço de novos fluxos sem quebrar histórico financeiro.
Novo valor ou nova cadência	Crie outro preço; o preço antigo pode receber `price.updated` com `is_active=false`.
Remoção real	Quando o preço 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_eH1zYAUYJAAv6nFa",
  "object": "event",
  "created_at": "2026-05-16T15:02:10Z",
  "data": {
    "object": {
      "id": "price_EyC4RjZ4WRGmF2so",
      "object": "price",
      "created_at": "2026-05-16T14:09:27Z",
      "currency": "brl",
      "is_active": false,
      "livemode": true,
      "metadata": {},
      "name": "Mensal",
      "product": "prod_i9MF5BfhP4GLopwL",
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "trial_period_days": null,
        "usage_type": "licensed"
      },
      "tax_behavior": "unspecified",
      "type": "recurring",
      "unit_amount": 9990,
      "updated_at": "2026-05-16T15:02:10Z"
    },
    "previous_attributes": {
      "is_active": true
    }
  },
  "livemode": true,
  "organization": "org_eqRQBQU6xVHJTVaC",
  "request": {
    "id": null
  },
  "type": "price.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento price.updated