Evento subscription.updated

Evento `subscription.updated`

Disparado quando uma subscription muda. data.object carrega o objeto completo no estado atual. data.previous_attributes traz apenas os campos que mudaram, com os valores anteriores. Use este evento para manter seu sistema sincronizado com mudanças de status, método de pagamento, período, cancelamento agendado, metadata ou itens da assinatura.

data.object é sempre a assinatura completa depois da mudança. Use data.previous_attributes para auditoria e notificações condicionais, mas atualize seu estado local a partir de data.object.

Quando acontece

Situação	Como aparece no payload
Assinatura pendente foi ativada após pagamento	`previous_attributes.status` pode vir como `incomplete` ou `past_due`, e `data.object.status: "active"`. Uma criação paga imediatamente já aparece `active` em `subscription.created`.
Método de pagamento mudou	`previous_attributes.default_payment_method` traz o valor anterior.
Encerramento no fim do ciclo foi agendado	`cancel_at_period_end: true` e `cancel_at` igual ao fim do período atual.
Prazo de término foi definido, alterado ou removido	`previous_attributes.cancel_at` traz a data anterior (ou `null`). Prazo declarado na criação já vem em `subscription.created`, sem um `updated` logo em seguida.
Agendamento entrou na última fase e vai encerrar	`cancel_at` passa a trazer a data do encerramento, disponível durante todo o último ciclo.
Metadata foi atualizada	`previous_attributes.metadata` mostra a metadata anterior.
Período avançou após renovação	`current_period_start`, `current_period_end` e `next_billing_at` mudam.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (sub_*) para atualizar a assinatura salva no seu sistema.
Atualize acesso e cobrança com base em data.object.status, não apenas nos campos do diff.
Use previous_attributes para decidir se deve enviar e-mail, registrar auditoria ou acionar fluxos internos.
Quando cancel_at mudar, reflita a data de término na sua UI. Ela cobre os três caminhos — prazo declarado na venda, agendamento que encerra e cancel_at_period_end —, então observar só o booleano deixa passar os dois primeiros.
Quando status mudar para active, reative acesso que estava bloqueado por pagamento pendente.

Campos importantes

Campo	O que observar
`data.object.status`	Estado atual depois da mudança.
`data.previous_attributes`	Valores anteriores dos campos públicos alterados.
`cancel_at`	Data de término, venha de prazo declarado, agendamento ou `cancel_at_period_end`. É o campo a observar.
`cancel_at_period_end`	Indica que o término foi expresso como “não renova depois deste ciclo”.
`default_payment_method`	Método usado nas próximas cobranças automáticas.
`current_period_start` / `current_period_end`	Janela de acesso e cobrança atual.
`latest_invoice`	Última invoice associada ao lifecycle da assinatura.
`pending_update`	Alteração pendente quando uma mudança ainda depende de pagamento ou expiração.
`metadata`	Dados livres para conciliação com seu sistema.

Exemplo de payload

{
  "id": "evt_5CiD32EK1A99uE9p",
  "object": "event",
  "created_at": "2026-05-20T12:00:00Z",
  "data": {
    "object": {
      "id": "sub_YvkiWxr7n75pAJtQ",
      "object": "subscription",
      "billing_cycle_anchor": "2026-05-19T18:00:00Z",
      "cancel_at": "2026-06-19T18:00:00Z",
      "cancel_at_period_end": true,
      "canceled_at": "2026-05-20T12:00:00Z",
      "cancellation_details": {
        "comment": "Cliente pediu cancelamento ao fim do ciclo atual.",
        "feedback": "too_expensive",
        "reason": "cancellation_requested"
      },
      "collection_method": "charge_automatically",
      "created_at": "2026-05-19T18:00:00Z",
      "currency": "brl",
      "current_period_end": "2026-06-19T18:00:00Z",
      "current_period_start": "2026-05-19T18:00:00Z",
      "customer": "cus_x7zxH7nvGuHvcBAN",
      "days_until_due": null,
      "default_payment_method": "pm_93JcAxUoVfPPm5Z4",
      "discount": "disc_ESMpWKBSZqanFuAp",
      "ended_at": null,
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_vDVM3DmFPrPpDfjD",
            "object": "subscription_item",
            "aggregate_usage": "sum",
            "amount_discount": 0,
            "amount_subtotal": 9900,
            "amount_tax": 0,
            "amount_total": 9900,
            "created_at": "2026-05-19T18:00:00Z",
            "currency": "brl",
            "discount": "disc_ESMpWKBSZqanFuAp",
            "metadata": {},
            "position": 0,
            "price": "price_HCKFCwVkHq3EPToN",
            "price_data": null,
            "product": "prod_mo9zUC3h5jtCdWj6",
            "quantity": 1,
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "subscription": "sub_YvkiWxr7n75pAJtQ",
            "unit_amount": 9900,
            "updated_at": "2026-05-20T12:00:00Z",
            "usage_period_end": "2026-06-19T18:00:00Z",
            "usage_period_start": "2026-05-19T18:00:00Z",
            "usage_type": "metered"
          }
        ],
        "has_more": false,
        "url": "/v1/subscription-items?subscription=sub_YvkiWxr7n75pAJtQ"
      },
      "latest_invoice": "inv_tZzzwr9gGScBGjDH",
      "livemode": true,
      "metadata": {},
      "next_billing_at": "2026-06-19T18:00:00Z",
      "pause_collection": null,
      "payment_settings": {},
      "pending_setup_intent": null,
      "pending_update": null,
      "resumed_at": null,
      "schedule": "subsched_RgZuWLtvjiARHGWe",
      "schedule_phase_index": 0,
      "start_date": "2026-05-19T18:00:00Z",
      "status": "active",
      "trial_end": null,
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "create_invoice"
        }
      },
      "trial_start": null,
      "updated_at": "2026-05-20T12:00:00Z"
    },
    "previous_attributes": {
      "default_payment_method": "pm_JXZRfVFgAYtZTaFq",
      "metadata": {}
    }
  },
  "livemode": true,
  "organization": "org_z9SLZ2E45gGUoWxm",
  "request": {
    "id": "req_VBz4BCaMJ1kdeWAD"
  },
  "type": "subscription.updated"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento subscription.updated