Clerk billing events and webhooks
Clerk billing supports webhook events that allow you to track information like subscription lifecycles and payments.
Subscriptions
A subscription is a top-level container unique to each user or organization. Subscription events can help you track billing changes for each of your customers.
| Event Name | Description |
|---|---|
subscription.created | The top-level subscription is created. This usually happens when a user or organization is created. For existing users and organizations, a subscription will be created when billing is enabled for the application. |
subscription.updated | The top-level subscription is updated. This event is triggered when any property of the subscription has changed, except for status changes. For example, when the subscription items for the payer change. |
subscription.active | The top-level subscription transitions to active from a non-active status. This happens when any subscription item is set to active, including items from the free default plan. |
subscription.pastDue | The top-level subscription contains a subscription item that has become past due. |
Subscription items
A subscription item provides details about the relationship between the payer (user or organization) and a plan. A top-level subscription may contain multiple subscription items.
There can only be one active subscription item per payer and plan. In addition, the subscription item for the default plan will always have the same id to allow easier tracking of which users and organizations are not paid customers.
| Event Name | Description |
|---|---|
subscriptionItem.updated | The subscription item is updated. This event is triggered when a property of the subscription item has changed that does not result in a status change. For example, when a subscription item is renewed and the recurring monthly charge succeeds, the status doesn't change (remains active), but period_start and period_end are updated. This results in a subscriptionItem.updated event. |
subscriptionItem.active | The subscription item is set to active. For paid plans, this happens on successful payment. |
subscriptionItem.canceled | The subscription item is canceled. The payer retains plan features until the end of the current billing period. |
subscriptionItem.upcoming | The subscription item is set as upcoming after the current billing period. This can happen in the case of a deferred plan change from a higher-priced to lower-priced plan. In the case a paid plan is canceled, the subscription item for the default, free plan will be set as upcoming. |
subscriptionItem.ended | The subscription item has ended. |
subscriptionItem.abandoned | The subscription item is abandoned. This can happen to upcoming subscription items if the payer subscribes to another plan, or re-subscribes to a currently canceled plan. |
subscriptionItem.incomplete | The subscription item is incomplete. This means the payer has started a checkout for a plan, but the payment hasn't been successfully processed yet. Once payment succeeds, the subscription item transitions to an active status. |
subscriptionItem.pastDue | The subscription item is past due because a recurring charge has failed. |
Payment attempts
Payment attempts allow you to track successful and failed payments, for both checkout and recurring charges.
Payment attempt events contain a type, which can be either checkout or recurring. You can use these values to determine whether a payment attempt was for a checkout or a subscription item renewal's recurring charge.
| Event Name | Description |
|---|---|
paymentAttempt.created | A payment attempt has been created with pending status. It can either succeed or fail in the future. |
paymentAttempt.updated | A payment attempt has been updated to paid or failed status. |
Feedback
Last updated on