subscription.* events

The busiest event family. Subscribe to these to drive CRM timelines, revenue dashboards, churn-risk pipelines, and Slack alerts.

Events

subscription.activated

Paid acquisition — the first successful payment on a subscription.

subscription.reactivated

Cancelled subscription re-activated before ends_at.

subscription.refunded

The whole charge came back; access is revoked.

subscription.upgraded

Subscriber moved to a higher-priced plan.

subscription.downgraded

Subscriber moved to a lower-priced plan.

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.

See the dedicated pages above for full payload, field reference, and caveats per event.

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 page.

{
  "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 GET /v1/subscriptions/{subscription} and GET /v1/projects/{project}/members/{member}.

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.

Required abilities

Tokens subscribing to subscription.* events must carry project-subscription:view.

subscription.* events

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

Example payload

Guarantees

Required abilities

On this page