Subscription events
Harness the power of subscription webhooks for efficient subscription status monitoring
Similar to
Guide
Implement webhooks for payments to automate event delivery and guarantee efficient event processing in your system.
payments,
merchants receive asynchronous notifications when using
subscription updates
Webhook
for any changes to the subscription.
The webhook structure is similar to the subscription status method, but with a callback_type parameter in the response object, indicating the nature of the subscription event that triggered the notification.
This comprehensive set of events offers detailed context and granularity, allowing merchants to be informed about the various subscription stages. It supports improved subscription management and analysis.
Merchants can track subscription states more effectively and make data-driven decisions to optimize their subscription-based revenue.
Merchants can track subscription states more effectively and make data-driven decisions to optimize their subscription-based revenue.
| Value | Description |
|---|---|
| create | A new subscription is created with a pending status, awaiting payment. |
| expire | A pending subscription expires during its creation process, for example, due to unsuccessful payment. |
| payment_attempt | An additional invoice representing a payment attempt was created while the subscription was in the pending status. |
| active | A notification is received about a successful payment, and the subscription status is updated to active. |
| renew | A new billing period for an active subscription begins, meaning that a recurring payment has succeeded. |
| recurring | The recurring billing process is initiated, and an order has been sent to the payment gateway. |
| order_update | A recurring subscription order status changes to settled or voided. The initial order for a subscription is refunded, voided, or settled. |
| pause_schedule.create | A new pause schedule is created for an active subscription. |
| pause_schedule.update | The existing pause schedule for an active or paused subscription is updated. |
| pause | An active subscription is automatically paused according to the pause schedule. |
| resume | A paused subscription is automatically resumed after the pause period ends. Or an active paused subscription is manually resumed via the API. |
| pause_schedule | A pause schedule for an active subscription is deleted. |
| redemption | A recurring subscription order is declined, and the subscription moves to the redemption period. |
| retry | An order is created for a subscription in the redemption period, attempting to retry the payment. |
| scheduled_for_retry | The next retry date is scheduled or updated for a subscription in the redemption period after the previous retry attempt was declined. |
| restore | A cancelled subscription, or one scheduled for cancellation while still in active status, is restored via the API or through mass operations. |
| switch_product | An active subscription is moved to a different product. |
| scheduled_for_cancellation | An active subscription is scheduled to be cancelled at the end of the current billing period by the scheduler after a soft cancel. |
| cancel | An active subscription can be force-cancelled for various reasons, such as by ID, by the customer via API, by mass operation, fraud or dispute events, stop declines, or other business cases. This can also involve a two-step cancellation, where a subscription previously scheduled for cancellation is officially cancelled at the end of its billing period. |
These events were the first version of callback types introduced to receive notifications for subscription events. They inform merchants about key subscription state changes, providing valuable updates on customer activities and subscription statuses.
Please be informed that the legacy version is going to be supported until the end of March 2026.
| Parameters | Condition |
|---|---|
| callback_type: init and status: active | The customer has successfully started the subscription. |
| callback_type: renew and status: active | The customer has successfully paid for the renewal of the subscription or restored a previously cancelled subscription. |
| callback_type:
update
and
status:
active subscription: cancelled_at | The customer requested to unsubscribe, and the support representative cancelled the subscription. The subscription remains active until the end of the current billing period. The cancelled_at parameter is required for this event, but its value is null in other cases, such as refunds. |
| callback_type: update and status: redemption | The subscription has entered the redemption period due to declined recurring payments. If all retries fail, the subscription status becomes cancelled . However, if any retry attempt is successful, the status reverts to active . |
| callback_type: pause and status: paused | An active subscription is automatically paused according to the pause schedule. |
| callback_type: pause_schedule.create and status: active | A pause plan is being established, including all relevant subscription and customer details. |
| callback_type: pause_schedule.update and status: active or paused | An existing pause plan is being modified, reflecting changes in dates and subscription specifics. |
| callback_type: pause_schedule.delete and status: active | A pause plan is being removed. This refers to the deletion of the pause plan, not resuming from a paused status. |
| callback_type: resume and status: active | The subscription is automatically resumed according to its schedule, resumed from a pause, or manually resumed. |
| callback_type: cancel and status: cancelled | The subscription is cancelled for any reason, including expiration of the subscription term, customer request, plan cancellation, failed payment attempts, or fraudulent activity. Specific reasons for cancellation are detailed in the cancel codes. |
The new extended version of events ensures enhanced event tracking and continued updates.
The legacy version of events reaches the end of support by the end of March 2026.
In case you have not switched by the deprecation date, the switch to the new version is going to happen automatically.
Periodic reminders help ensure a smooth migration, giving you time to adjust your plans and update your tech roadmap.
To start receiving webhooks, you need to subscribe to the new Subscription updates event. If you do not have the new extended statutes activated, the following webhooks cannot be received:
- create
- expire
- payment_attempt
To subscribe to Subscription updates
- Go to Developers > Channels.
- Find the needed channel and click on it.
- In the Webhooks section, select +Add an endpoint.
- In the appeared form:
- Select Subscription updates from the dropdown list
- Specify URL
- Click on Add to save changes and start receiving the extended events.
Looking for help? Contact us
Stay informed with Changelog