subscription.* events

Every transition across the subscription statuses, plus upgrade / downgrade. The busiest event family. Subscribe to these to drive CRM timelines, revenue dashboards, churn-risk pipelines, and Slack alerts.

Event	Fires when
`subscription.created`	An access code is redeemed, or a cardless trial starts. Never a paid checkout.
`subscription.activated`	A paid subscription is acquired. Fires once, on the first successful payment.
`subscription.trial_started`	A trial-enabled plan starts its free window.
`subscription.trial_converting`	A trial is about to convert. Fires 24h before conversion.
`subscription.trial_expired`	A trial ended without converting.
`subscription.renewed`	Recurring billing charges the subscriber successfully.
`subscription.reactivated`	A cancelled subscription is re-activated before `ends_at`.
`subscription.paused`	Subscription paused by creator or subscriber.
`subscription.unpaused`	A paused subscription resumes.
`subscription.past_due`	Billing fails but grace period is active.
`subscription.unpaid`	Billing permanently failed; grace expired.
`subscription.cancelled`	Cancellation recorded, access continues until `ends_at`.
`subscription.expired`	`ends_at` reached; access revoked.
`subscription.refunded`	The whole charge came back; the subscription is expired and access revoked. Partial refunds emit `payment.refunded` only.
`subscription.upgraded`	Subscriber moved to a higher-priced plan.
`subscription.downgraded`	Subscriber moved to a lower-priced plan.

Example payload

subscription.* payloads carry flat identifier fields, not nested subscription / plan / subscriber objects. Every event in the family includes subscription_id and subscriber_id. All of them except subscription.upgraded and subscription.downgraded also include plan_id; those two carry from_plan_id and to_plan_id instead. The remaining keys vary per event, so check the individual event.

{
  "id": "evt_01HX...",
  "type": "subscription.activated",
  "created_at": "2026-05-18T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "provider": "stripe"
  }
}

Plan pricing, subscriber identity, and period boundaries are not embedded. Resolve them with the subscription endpoint and the member endpoint.

Guarantees

Every acquisition emits exactly one of subscription.activated (paid) or subscription.created (access code, cardless trial), never both. Subscribe to both and de-duplicate on data.subscription_id to cover all acquisition paths.
subscription.activated fires at most once per subscription. Renewals emit subscription.renewed instead.
Out-of-order delivery is possible during retries. Use SB-Event-Id to de-dupe and created_at to sequence.

subscription.* events

Example payload

Guarantees

Required abilities

Events

subscription.created

subscription.activated

subscription.trial_started

subscription.trial_converting

subscription.trial_expired

subscription.renewed

subscription.reactivated

subscription.paused

subscription.unpaused

subscription.past_due

subscription.unpaid

subscription.cancelled

subscription.expired

subscription.refunded

subscription.upgraded

subscription.downgraded

Compare with the current pages

subscription.* events overview

On this page