Evento subscription.pending.update.expired

Evento `subscription.pending.update.expired`

Disparado quando uma pending update expira antes de ser aplicada. data.object carrega o objeto subscription completo no estado atual. data.previous_attributes traz a pending update removida. Use este evento para cancelar no seu sistema uma troca de plano, quantidade ou itens que dependia de uma condição e não foi concluída a tempo. A assinatura continua no estado anterior.

Quando acontece

Situação	Como aparece no payload
Pending update venceu antes de aplicar	`pending_update: null` em `data.object`.
Alteração removida do lifecycle	`previous_attributes.pending_update` traz a mudança que expirou.
Assinatura permaneceu no plano anterior	`items.data[]` mostra os itens atuais preservados.
Invoice de ajuste não confirmou a mudança	A invoice associada pode aparecer dentro de `previous_attributes.pending_update.invoice`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (sub_*) para manter a assinatura no estado atual recebido.
Remova marcações internas de upgrade/downgrade pendente.
Avise o cliente se a mudança dependia de pagamento, confirmação ou ação manual.
Use previous_attributes.pending_update para mostrar qual alteração expirou.

Campos importantes

Campo	O que observar
`data.object.pending_update`	`null` depois que a pending update expirou.
`data.previous_attributes.pending_update`	Alteração que não foi aplicada.
`items.data[]`	Itens atuais que continuam valendo.
`latest_invoice`	Última invoice conhecida da assinatura.
`status`	Estado preservado da assinatura.
`updated_at`	Momento em que a expiração foi refletida.

Exemplo de payload

{
  "id": "evt_zHoBnqAwqHNbncpX",
  "object": "event",
  "created_at": "2026-05-20T12:30:00Z",
  "data": {
    "object": {
      "id": "sub_4mTJzDrUSDhyVk3s",
      "object": "subscription",
      "billing_cycle_anchor": "2026-05-19T18:00:00Z",
      "cancel_at": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "cancellation_details": {
        "comment": null,
        "feedback": null,
        "reason": null
      },
      "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_SNMFjz7fh4hhyrgJ",
      "days_until_due": null,
      "default_payment_method": "pm_XUqyHtc8KqdPT5eJ",
      "discount": "disc_kxh1P4b69S7mfR8L",
      "ended_at": null,
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_dunYMLZbjVY8jZ8D",
            "object": "subscription_item",
            "aggregate_usage": "sum",
            "amount_discount": 0,
            "amount_subtotal": 10000,
            "amount_tax": 0,
            "amount_total": 10000,
            "created_at": "2026-05-19T18:00:00Z",
            "currency": "brl",
            "discount": "disc_kxh1P4b69S7mfR8L",
            "metadata": {},
            "position": 0,
            "price": "price_HpFQwyyD6Cf3q2ZY",
            "price_data": null,
            "product": "prod_aF9p5SZJ1dXYhqXL",
            "quantity": 1,
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "subscription": "sub_4mTJzDrUSDhyVk3s",
            "unit_amount": 10000,
            "updated_at": "2026-05-19T18: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_4mTJzDrUSDhyVk3s"
      },
      "latest_invoice": "inv_ewzLLjTwcKebDzkf",
      "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_K3HgoFHe48sSSq6h",
      "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:30:00Z"
    },
    "previous_attributes": {
      "pending_update": {
        "expires_at": "2026-05-20T12:30:00Z",
        "invoice": "inv_ewzLLjTwcKebDzkf",
        "subscription_items": [
          {
            "id": "evt_2AgRoCbbkzxgAS7N",
            "metadata": {},
            "price": "price_HpFQwyyD6Cf3q2ZY",
            "price_data": null,
            "quantity": 3
          }
        ]
      },
      "updated_at": "2026-05-20T11:58:00Z"
    }
  },
  "livemode": true,
  "organization": "org_1KRYN8Sgq1a2pLp8",
  "request": {
    "id": null
  },
  "type": "subscription.pending.update.expired"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento subscription.pending.update.expired

Evento `subscription.pending.update.expired`

Quando acontece

Como processar

Campos importantes

Exemplo de payload

​Evento subscription.pending.update.expired

​Quando acontece

​Como processar

​Campos importantes

​Exemplo de payload

Evento `subscription.pending.update.expired`

Quando acontece

Como processar

Campos importantes

Exemplo de payload