subscription.* events
Every transition across the subscription statuses, plus upgrade / downgrade.
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.
Background
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) orsubscription.created(access code, cardless trial), never both. Subscribe to both and de-duplicate ondata.subscription_idto cover all acquisition paths. subscription.activatedfires at most once per subscription. Renewals emitsubscription.renewedinstead.- Out-of-order delivery is possible during retries. Use
SB-Event-Idto de-dupe andcreated_atto sequence.
Required abilities
Tokens subscribing to subscription.* events must carry project-subscription:view.
Events
subscription.createdNew subscription created via access-code redemption or cardless trial.subscription.activatedA paid subscription is acquired. Fires once, at first activation.subscription.trial_startedTrial-enabled plan starts free window.subscription.trial_convertingTrial about to convert. Fires 24h before `trial_ends_at`.subscription.trial_expiredTrial ended without conversion.subscription.renewedRecurring billing successfully charged the subscriber.subscription.reactivatedCancelled subscription re-activated before `ends_at`.subscription.pausedA member's access was suspended. Billing is unaffected and continues on schedule.subscription.unpausedPaused subscription resumes; resource invite links re-issued.subscription.past_dueBilling fails but grace period is active.subscription.unpaidBilling permanently failed; grace expired.subscription.cancelledCancellation recorded; access continues until `ends_at`.subscription.expired`ends_at` reached; access revoked.subscription.refundedRefund recorded against a subscription.subscription.upgradedSubscriber moved to a higher-priced plan.subscription.downgradedSubscriber moved to a lower-priced plan.subscription.payment_recoveredA failed renewal was settled, and the grace clock on the subscription closed.subscription.access_suspendedA failed renewal's grace window closed unpaid, and the member's access was paused.subscription.access_restoredA member whose access was paused for non-payment was let back in.subscription.cancellation_feedbackA cancelling member said why they are leaving.subscription.offer_takenA cancelling member took the offer the cancellation screen made.How is this guide?
Last updated on