subscription.* events
Every transition across the 13 subscription statuses, plus upgrade / downgrade.
The busiest event family. Subscribe to these to drive CRM timelines, revenue dashboards, churn-risk pipelines, and Slack alerts.
Events
subscription.created
New subscription becomes active.
subscription.activated
Non-active subscription transitions to active.
subscription.trial_started
Trial-enabled plan starts free window.
subscription.trial_converting
24h before trial conversion.
subscription.trial_expired
Trial ended without conversion.
subscription.renewed
Recurring billing succeeded.
subscription.reactivated
Cancelled subscription re-activated before ends_at.
subscription.paused
Subscription paused by creator.
subscription.unpaused
Paused subscription resumes.
subscription.past_due
Billing fails but grace period active.
subscription.unpaid
Billing permanently failed.
subscription.cancelled
Cancellation recorded.
subscription.expired
ends_at reached; access revoked.
subscription.refunded
Refund recorded against subscription (deferred).
subscription.upgraded
Subscriber moved to a higher-priced plan.
subscription.downgraded
Subscriber moved to a lower-priced plan.
| Event | Fires when |
|---|---|
subscription.created | A new subscription row becomes active via paid checkout, access code redemption, or trial activation. |
subscription.activated | A non-active subscription (trial, paused) transitions to active. |
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 | Payment refunded; subscription may or may not be terminated. |
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.
Example payload
{
"id": "evt_01HX...",
"type": "subscription.created",
"created_at": "2026-05-18T10:05:00Z",
"api_version": "2026-05-01",
"project_id": "prj_01HX...",
"data": {
"subscription": {
"id": "sub_01HX...",
"plan_id": "pln_01HX...",
"subscriber_id": "usr_01HX...",
"status": "active",
"trial_ends_at": null,
"ends_at": "2026-06-18T10:05:00Z"
},
"plan": {
"id": "pln_01HX...",
"name": "Premium Monthly",
"price": 29.0,
"currency": "USD"
},
"subscriber": {
"id": "usr_01HX...",
"telegram_user_id": "123456789",
"email": null
}
}
}Guarantees
subscription.createdalways precedesmember.joinedandpayment.succeededfor paid plans.- Each transition fires exactly once per subscription per state change.
- Out-of-order delivery is possible during retries — use
MP-Event-Idto de-dupe andcreated_atto sequence.
Required abilities
Tokens subscribing to subscription.* events must carry project-subscription:view-any.
How is this guide?