subscription.upgraded

When this fires

A subscriber is switched to a higher-priced plan on the same project. The plan assignment, currency, and stored price on the Subscriby subscription record are updated, and this event reports the move.

The switch does not itself perform a provider-side pro-ration or issue a charge. Any billing adjustment is whatever the provider does on the next cycle.

Required ability

project-subscription:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "subscription.upgraded",
  "created_at": "2026-05-22T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "from_plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "to_plan_id": "e07b4a29-51c6-4d83-9f10-2b8ac635d174",
    "proration_amount": null
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `subscription.upgraded` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID	Project this event belongs to.
`data.subscription_id`	string UUID	Subscription identifier.
`data.subscriber_id`	string UUID	Subscriber's project-scoped user id.
`data.from_plan_id`	string UUID	Plan id the subscription was on prior to the change.
`data.to_plan_id`	string UUID	Plan id the subscription is now on.
`data.proration_amount`	null	Reserved. Always `null` — pro-ration is not yet computed for this event.

Caveats

Direction is decided by comparing the two plan prices, normalised to USD, at switch time. Only a strictly higher new price emits subscription.upgraded — an equal-price switch emits subscription.downgraded, which is worth guarding for if you offer same-price plan swaps.
Trial windows do not carry across switches; if the destination plan has a trial it does not start.

subscription.downgraded — opposite direction.
payment.succeeded — the next successful charge on the new plan.
Subscription events overview — back to family overview.