Handle subscription events

Set up subscription webhooks in Solidgate to receive real-time notifications on status changes and automate subscription management

Similar to payments, merchants receive asynchronous notifications when using subscription updatesWebhook 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 event set provides detailed context for each subscription stage, giving merchants visibility into the full subscription lifecycle. 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.

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. If the subscription has multiple invoices, this event is only sent for the most recent invoice at the time the order status changes. Webhooks for orders on older invoices are suppressed. To receive events for all order updates regardless of invoice status, subscribe to `card_gate.order.updated` and `alt_gate.order.updated` event types.
`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. This event also fires when an upgrade charge fails and the subscription reverts to the original 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.

The legacy version is supported until the end of August 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. Each cancellation carries a cancel code with the specific reason.

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 August 2026. If you have not switched by the deprecation date, the migration happens automatically. Periodic reminders are sent before the deadline, 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 statuses activated, the following webhooks cannot be received:

create
expire
payment_attempt

Looking for help? Contact us

Stay informed with Changelog