Subscription cancellations let you control how and when customers stop their subscriptions. You can cancel immediately or at the end of the billing period. Automatic cancellations may also occur when all payment retries are exhausted during the redemption window.
Each cancellation includes a reason code that explains why the subscription was terminated. By analyzing cancellation reasons, you can identify churn patterns and take steps to improve retention.
Cancellation options
Solidgate subscriptions support two cancellation modes that you specify when calling the cancel endpoint or selecting an option in the Hub.
-
Cancel at period end
The subscription remains active until the current billing period ends. The customer retains access to the product during this time. No further invoices are generated after the period ends, and the status changes to CANCELLED automatically. -
Cancel immediately
The subscription status changes to CANCELLED right away. No further invoices are generated. Use this when you need to terminate billing immediately, for example, due to fraud, dispute, or a mutual agreement to stop the service.
Cancellation is a terminal state. If the customer wants to resubscribe, create a new subscription.
Before cancelling, select the mode that best matches your use case.
| Action | When to use | Impact |
|---|---|---|
| Cancel at period end | Customer confirms they want to leave but should retain access until the current period ends. | Status stays active until the period ends, then moves to CANCELLED . No further charges after the current period. |
| Cancel immediately | Immediate termination is needed due to fraud, dispute, or mutual agreement. | Status changes to CANCELLED immediately. No further charges. Terminal state. |
Automatic cancellations
- A renewal payment fails, and the subscription enters the REDEMPTION status.
- Solidgate retries the payment using smart retries.
- All retries are exhausted without a successful payment.
- The subscription moves to either UNPAID or CANCELLED .
Automatic subscription cancellation results in the DUNNING_EXHAUSTED reason code.
For retry configuration, see smart retries.
Cancel subscription
When a subscription is cancelled, Solidgate records a reason code in the
cancellation_info object, along with requested_at, cancel_at, and comment.
| Reason | Description |
|---|---|
| CANCELLATION_REQUESTED | The merchant or customer requested cancellation through the API or Hub. |
| DUNNING_EXHAUSTED | All payment retries were exhausted during the redemption window. The subscription was cancelled automatically. |
- Go to Billing > Billing 2.0 > Subscriptions.
- Click on the subscription ID to open the details page.
- Click on Cancel.
- Choose to cancel immediately or at the end of the billing period.
- Optionally, provide a cancellation comment.
- Click on Cancel subscription to confirm the cancellation.
Handle events
Solidgate sends webhook events when a subscription is cancelled or scheduled for cancellation.
| Event | Description |
|---|---|
| SUBSCRIPTION_CANCELLED | Sent when NOW mode is used and the subscription is cancelled immediately, or when a PERIOD_END cancellation takes effect at the end of the billing period. |
| SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION | Sent when PERIOD_END mode is used. The cancellation is scheduled and the subscription remains active until the billing period ends. |
Listen for SUBSCRIPTION_CANCELLED to revoke access to your product. For end-of-period cancellations, you can also listen for SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION to notify the customer or trigger a retention flow before the cancellation takes effect.