Skip to main content
Docs

Clerk billing events and webhooks

Warning

This feature is currently in Beta. The low-level JavaScript APIs exposed via Clerk.billing are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend pinning your SDK and clerk-js package versions.

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 NameDescription
subscription.createdThe 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.updatedThe 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.activeThe 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.pastDueThe 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 NameDescription
subscriptionItem.updatedThe 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.activeThe subscription item is set to active. For paid plans, this happens on successful payment.
subscriptionItem.canceledThe subscription item is canceled. The payer retains plan features until the end of the current billing period.
subscriptionItem.upcomingThe 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.endedThe subscription item has ended.
subscriptionItem.abandonedThe 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.incompleteThe 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.pastDueThe 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 NameDescription
paymentAttempt.createdA payment attempt has been created with pending status. It can either succeed or fail in the future.
paymentAttempt.updatedA payment attempt has been updated to paid or failed status.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on