subscription.updated

Fires whenever any field on a subscription changes — plan swap, quantity bump, metadata edit, status transition. The envelope's data.previous_attributes tells you what changed.

Payload

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "subscription.updated",
  "created": 1705689600,
  "livemode": true,
  "data": {
    "object": {
      "id": "sub_01HK4X7Z2M5N8P0Q3R6S9T2V5",
      "object": "subscription",
      "status": "active",
      "customer_id": "cus_01HK4X7Z2M5N8P0Q3R6S9T2V5",
      "price_id": "price_01HK4X7Z2M5N8P0Q3R6S9T2V5",
      "quantity": 5,
      "current_period_start": "2026-01-01T00:00:00Z",
      "current_period_end": "2026-02-01T00:00:00Z",
      "cancel_at_period_end": false,
      "trial_end": null,
      "metadata": {}
    },
    "previous_attributes": {
      "quantity": 3
    }
  }
}

Common triggers

Handler contract

1. Verify the signature.
2. Deduplicate by event.id.
3. Read data.object for the current state — do not reconstruct state from previous_attributes.
4. If status: canceled and your entitlement model cuts off immediately → revoke access.
5. If cancel_at_period_end: true → mark the account to revoke at current_period_end (via scheduled job or cron).
6. Return 2xx.

Narrower alternatives

If you only care about:

• Cancellation → subscribe to subscription.canceled, not subscription.updated
• Renewals → subscribe to subscription.renewed (fires after the payment succeeds for the new period)
• Trial ending → subscribe to subscription.trial_will_end (fires 3 days before the end)

Narrower subscriptions = fewer handler invocations + less dedup work.

Related events

• subscription.created — new subscription
• subscription.canceled — fully cancelled
• subscription.renewed — renewal succeeded
• subscription.trial_will_end — 3-day warning
• invoice.paid — matching invoice-level event on renewals