Evento subscription.pending.update.applied

Evento `subscription.pending.update.applied`

Disparado quando uma pending update é aplicada à subscription. data.object carrega o objeto subscription completo no estado atual. data.previous_attributes traz a pending update anterior e os demais campos alterados. Pending updates são alterações que ficaram aguardando uma condição antes de entrar em vigor, como pagamento de uma invoice de ajuste. Use este evento para trocar plano, quantidade ou itens no seu sistema somente quando a mudança foi efetivamente aplicada.

Quando acontece

Situação	Como aparece no payload
Alteração pendente foi aplicada	`pending_update: null` em `data.object`.
Itens ou quantidades mudaram	`items.data[]` traz o estado novo e `previous_attributes.items` mostra o anterior.
Invoice de ajuste foi concluída	`latest_invoice` aponta para a invoice associada à aplicação.
Metadata ou datas mudaram junto	`previous_attributes` inclui apenas os campos públicos alterados.

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.
Aplique acesso, limites e cobrança com base em data.object.items.data[], que já é o estado novo.
Use previous_attributes.pending_update para auditoria ou para fechar uma solicitação pendente no seu sistema.
Não aplique a mudança duas vezes se você também recebeu eventos da invoice relacionada.

Campos importantes

Campo	O que observar
`data.object.pending_update`	`null` quando a alteração pendente já foi consumida.
`data.previous_attributes.pending_update`	Descreve a alteração que estava pendente antes de ser aplicada.
`items.data[]`	Itens, preços e quantidades atuais depois da aplicação.
`latest_invoice`	Invoice ligada à alteração aplicada, quando houver.
`status`	Estado atual da assinatura depois da mudança.
`metadata`	Dados livres para conciliação com contrato ou workspace.

Exemplo de payload

{
  "id": "evt_Mx2nRMdHQGz2D9da",
  "object": "event",
  "created_at": "2026-05-20T12:00:00Z",
  "data": {
    "object": {
      "id": "sub_3a5J3XmfKpsjyw2p",
      "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_GBFBi5jUMbW4mJL5",
      "days_until_due": null,
      "default_payment_method": "pm_SFS9D9j8cdHBVCQ5",
      "discount": "disc_E4VGnh8h3AmJXPND",
      "ended_at": null,
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_4Ux7TQf4kmwvHCVW",
            "object": "subscription_item",
            "aggregate_usage": "sum",
            "amount_discount": 0,
            "amount_subtotal": 30000,
            "amount_tax": 0,
            "amount_total": 30000,
            "created_at": "2026-05-19T18:00:00Z",
            "currency": "brl",
            "discount": "disc_E4VGnh8h3AmJXPND",
            "metadata": {},
            "position": 0,
            "price": "price_ReCtUD9g2e8LaKrP",
            "price_data": null,
            "product": "prod_V2s5e9oukUiYZPm8",
            "quantity": 3,
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "subscription": "sub_3a5J3XmfKpsjyw2p",
            "unit_amount": 10000,
            "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_3a5J3XmfKpsjyw2p"
      },
      "latest_invoice": "inv_j9QvSwADeRaNbKnr",
      "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_AQ1ykXF9WmUntbM5",
      "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": {
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_4Ux7TQf4kmwvHCVW",
            "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_E4VGnh8h3AmJXPND",
            "metadata": {},
            "position": 0,
            "price": "price_ReCtUD9g2e8LaKrP",
            "price_data": null,
            "product": "prod_V2s5e9oukUiYZPm8",
            "quantity": 1,
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "subscription": "sub_3a5J3XmfKpsjyw2p",
            "unit_amount": 10000,
            "updated_at": "2026-05-20T11:58: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_3a5J3XmfKpsjyw2p"
      },
      "pending_update": {
        "expires_at": "2026-05-20T12:30:00Z",
        "invoice": "inv_j9QvSwADeRaNbKnr",
        "subscription_items": [
          {
            "id": "evt_zMQmE49iC4vGCKxJ",
            "metadata": {},
            "price": "price_ReCtUD9g2e8LaKrP",
            "price_data": null,
            "quantity": 3
          }
        ]
      },
      "updated_at": "2026-05-20T11:58:00Z"
    }
  },
  "livemode": true,
  "organization": "org_xNLtXbPoKYY531rj",
  "request": {
    "id": null
  },
  "type": "subscription.pending.update.applied"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento subscription.pending.update.applied

Evento `subscription.pending.update.applied`

Quando acontece

Como processar

Campos importantes

Exemplo de payload

​Evento subscription.pending.update.applied

​Quando acontece

​Como processar

​Campos importantes

​Exemplo de payload

Evento `subscription.pending.update.applied`

Quando acontece

Como processar

Campos importantes

Exemplo de payload