billing.tier_downgraded

project_id is always null for billing events.

When this fires

The creator switches their Subscriby subscription to a lower tier. The change lands at the end of the period they have already paid for, not at effective_at: the current phase runs to its existing end date and the lower tier begins after it.

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": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "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 UUID	Creator whose tier changed.
`data.from_tier`	string UUID	Previous tier plan id. Always present — a first subscription emits no tier event.
`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 once the current paid period ends — never at effective_at.

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