Webhook Events

​

Billing Events

​

Checkout

​

Customers

​

Subscriptions

In order to properly implement logic for handling subscriptions, you should look into the following events.

​

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:

1. subscription.updated
2. subscription.canceled

Both events contain the same subscription data. The subscription will still have 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:

3. subscription.updated
4. subscription.revoked

Both events contain the same subscription data. The subscription will have the canceled status. Immediate Revocation When a merchant cancels a subscription with immediate revocation, those events are sent at once:

1. subscription.updated
2. subscription.canceled
3. subscription.revoked

All three events contain the same subscription data. The subscription will have the 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):

1. subscription.cycled
2. subscription.updated
3. order.created

subscription.cycled fires only on a new billing period, so you can act on a renewal without inspecting billing_reason on the order. It also fires when a trial converts to a paid subscription, since that starts a period too: read status to tell the two apart. The subscription data will reflect the new billing period through the 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:

4. order.updated
5. order.paid

Both events will contain the same order data, with the order status changed to paid.

​

Pause Sequences

Pausing is scheduled for the end of the current billing period, much like an end-of-period cancellation. When a subscription is paused (by customer action from the portal or by the merchant from the dashboard/API), only one event is sent immediately, because the subscription stays active until the period ends:

1. subscription.updated

The pause_at_period_end flag is set to true, and resumes_at holds the scheduled resume date if you set one. When the end of the current billing period arrives, the pause takes effect: billing stops and benefits are revoked. The following events are then sent:

2. subscription.updated
3. subscription.paused

Both events contain the same subscription data, now with the paused status. Resume When a paused subscription resumes, either immediately when you resume it or automatically on its resumes_at date, a new billing period starts and the customer is charged right away. The following events are sent:

1. subscription.updated
2. subscription.resumed
3. order.created

The subscription data reflects the new period through current_period_start and current_period_end, and the order represents the immediate charge for the new cycle.

​

Orders

​

Refunds

​

Benefit Grants

​

Organization Events

​

Benefits

​

Products

​

Discounts

​

Organization