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 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 NOW |
Immediate termination is needed due to fraud, dispute, or mutual agreement. | Status changes to CANCELLED immediately. No further charges. Terminal state. |
Automatic cancellations
Subscriptions can be cancelled automatically if all payment retries are exhausted during the redemption window:- 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
API Send a request to the cancel subscription API v2 endpoint with the subscription ID and the cancellation mode. Pass NOW to cancel immediately or PERIOD_END to cancel at the end of the current billing period. Optionally, include a comment with a free-text cancellation reason.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. |
| FRAUD_ALERT_RECEIVED | The subscription was cancelled automatically based on a fraud alert. |
| DISPUTE_RECEIVED | The subscription was cancelled automatically based on a chargeback or dispute alert. |
- 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.
Alert-based cancellation
In addition to manual cancellation, Solidgate supports automatic subscription cancellation based on alerts for card payments and PayPal. Alert-based cancellation helps manage risk and reduce chargeback rates automatically.
You can set up alert-based cancellation with two settings:
-
What to cancel
- Do not cancel anything – keeps all subscriptions active and applies to Inquiry alerts.
- Only affected subscriptions – cancels the subscriptions directly related to the alert.
- All customer subscriptions – cancels all active subscriptions for the customer.
-
When to cancel
- At billing period end ( PERIOD_END ) – keeps the subscription active until the current billing period ends.
- Immediately ( NOW ) – cancels the subscription right away.
Card payments and PayPal subscriptions follow auto-cancellation rules based on specific alerts. The tables below show the available options for each alert type, based on the selected scope and timing. ✓ marks the default setting.
Card payments
| Alert type | Do not cancel | Cancel only affected subscriptions | Cancel all customer subscriptions | |||
|---|---|---|---|---|---|---|
| At the end | Immediately | At the end | Immediately | |||
| Fraud alert | ✓ | ✓ | ✓ | ✓ | ||
| Prevention alert | Inquiry | ✓ | ✓ | ✓ | ✓ | ✓ |
| Init refund | ✓ | ✓ | ✓ | ✓ | ||
| Resolved | ✓ | ✓ | ✓ | ✓ | ||
| Chargeback | ✓ | ✓ | ✓ | ✓ | ||
PayPal
| Alert type | Do not cancel | Cancel only affected subscriptions | Cancel all customer subscriptions | |||
|---|---|---|---|---|---|---|
| At the end | Immediately | At the end | Immediately | |||
| External chargeback | ✓ | ✓ | ✓ | ✓ | ||
| Alert | ✓ | ✓ | ✓ | ✓ | ||
| ClaimInternal chargeback | ✓ | ✓ | ✓ | ✓ | ||
| Inquiry | ✓ | ✓ | ✓ | ✓ | ✓ | |
Alert-based cancellations use the following cancellation_info values:
- DISPUTE_RECEIVED for chargeback-stage alerts, including card chargeback and PayPal external chargeback, claim, and alert.
- FRAUD_ALERT_RECEIVED for fraud-related alerts, including card fraud alert, all prevention alerts, and PayPal inquiry.
Depending on the selected timing, alert-based cancellations send the same SUBSCRIPTION_CANCELLED or SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION webhook events described in handle events. The SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION event is sent only when the subscription is in ACTIVE or TRIALING status. Otherwise, the subscription is cancelled immediately, and the SUBSCRIPTION_CANCELLED event is sent instead, even if At billing period end is selected.
You can apply and manage these cancellation rules in the Hub.
Hub To set up cancellation rules- Go to Billing > Billing settings.
- Navigate to Subscription cancellation > Cards or PayPal.
- Select the preferred option for each alert type to define what and when to cancel.
Changes are saved and applied automatically.
Delete scheduled cancellation
If you have scheduled a subscription cancellation that you need to remove, you can delete it before the billing period ends. The subscription continues on the same plan and billing schedule, and the next renewal date remains unchanged.
You can delete a scheduled cancellation only for a subscription in ACTIVE or TRIALING status with a PERIOD_END cancellation. API Send a request to the delete subscription cancellation API v2 endpoint with the id of the subscription. If you use multiple channels, also include the channel_id . The response returns the updated subscription object.Handle events
Solidgate sends webhook events after you cancel a subscription, schedule it for cancellation, or delete a scheduled cancellation.
| Event | Description |
|---|---|
| SUBSCRIPTION_CANCELLED | Sent when you cancel immediately using NOW mode, or when a PERIOD_END cancellation takes effect at the end of the billing period. |
| SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION | Sent when you schedule a cancellation using PERIOD_END mode. The subscription remains active until the billing period ends. |
| SUBSCRIPTION_UPDATED | Sent when you delete a scheduled PERIOD_END cancellation. The subscription stays ACTIVE or TRIALING , and the cancellation no longer appears as scheduled. |
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. Listen for SUBSCRIPTION_UPDATED to detect when a scheduled cancellation is deleted and update your own records accordingly.