subscription.downgraded

When this fires

A subscriber is switched to a lower-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 credit. 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.downgraded",
  "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": "e07b4a29-51c6-4d83-9f10-2b8ac635d174",
    "to_plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "proration_amount": null
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `subscription.downgraded` 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

No credit or refund is issued by this action. If you owe subscribers a mid-cycle credit on downgrade, apply it yourself through the provider.
Direction is decided by comparing the two plan prices, normalised to USD. Anything that is not strictly more expensive lands here — so a switch between two equally-priced plans emits this event, not subscription.upgraded.
Resource access tied to the higher tier may be revoked on the next renewal cycle.

subscription.upgraded — opposite direction.
member.resource_removed — emitted when premium-tier resources are detached.
Subscription events overview — back to family overview.