Billing Events
Checkout
checkout.created
checkout.updated
Customers
customer.created
Fired when a new customer has been created.
customer.updated
Fired when a customer has been updated.
customer.deleted
Fired when a customer has been deleted.
customer.state_changed
Fired when a customer’s state has changed. Includes active subscriptions and
granted benefits.
Subscriptions
In order to properly implement logic for handling subscriptions, you should look into the following events.subscription.created
Fired when a new subscription has been created.
subscription.updated
Use this event if you want to handle cancellations, un-cancellations, etc. The
updated event is a catch-all event for
subscription.active ,
subscription.canceled, subscription.uncanceled and subscription.revoked.order.created
In case you want to do logic when a subscription is renewed, you should listen
to
order.created and the billing_reason field. It can be purchase,
subscription_create, subscription_cycle and subscription_update.
subscription_cycle is used when subscriptions renew.subscription.active
subscription.canceled
subscription.uncanceled
subscription.revoked
Cancellation Sequences
When a subscription is canceled, the events triggered depend on whether the cancellation is immediate or scheduled for the end of the billing period. End-of-Period Cancellation (default) When a subscription is canceled (by customer action from the portal or by the merchant from the dashboard/API), the following events are sent immediately:subscription.updatedsubscription.canceled
active status, but the cancel_at_period_end flag will be set to true.
When the end of the current billing period arrives, the subscription is definitively revoked: billing cycles stop and benefits are revoked. The following events are then sent:
subscription.updatedsubscription.revoked
canceled status.
Immediate Revocation
When a merchant cancels a subscription with immediate revocation, those events are sent at once:
subscription.updatedsubscription.canceledsubscription.revoked
canceled status immediately.
Renewal Sequences
When a subscription is renewed for a new cycle, the webhook events are triggered in a specific sequence to help you track the renewal process and handle billing logic appropriately. Initial Renewal Events When a subscription reaches its renewal date, the following events are sent immediately (if enabled on the webhook):subscription.updatedorder.created
current_period_start and current_period_end properties, showing the updated cycle dates.
The order data represents the new invoice for the upcoming cycle, with a total representing what the customer will pay for this new period. If usage-based billing is involved, their consumption for the past period will be included in the total. The status of this order is pending at this stage.
Payment Processing Events
Shortly after the initial renewal events, the platform will trigger a payment for the new order. Once the payment is successfully processed, the following events are sent:
order.updatedorder.paid
paid.