billing.tier_downgraded

project_id is always null for billing events.

When this fires

The creator switches their Subscriby subscription to a lower tier. Tier-locked features become unavailable from effective_at onward.

Required ability

billing:read — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "billing.tier_downgraded",
  "created_at": "2026-05-18T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": null,
  "data": {
    "creator_id": "cre_01HX...",
    "from_tier": "882b72bb-1eb6-11f0-b4f2-d8bbc173f8c3",
    "to_tier": "308eb3da-1eb6-11f0-b4f2-d8bbc173f8c3",
    "effective_at": "2026-05-18T10:05:00Z"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `billing.tier_downgraded` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	null	Always `null` — account-level event.
`data.creator_id`	string ULID	Creator whose tier changed.
`data.from_tier`	string UUID \| null	Previous tier plan id, or `null` if none was active.
`data.to_tier`	string UUID	New tier plan id.
`data.effective_at`	ISO 8601 timestamp	Always the emission time — never a future date.

Caveats

effective_at is stamped at emission time and is never in the future, even when the provider defers the billing change to the next renewal boundary. Do not use it to schedule feature revocation.
Tier-locked features (Teams, custom roles, etc.) may become read-only or hidden after effective_at.

billing.tier_upgraded — opposite direction.
billing.tier_cancelled — terminal downgrade path.
Billing events overview — back to family overview.