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:

  1. A renewal payment fails, and the subscription enters the REDEMPTION status.
  2. Solidgate retries the payment using smart retries.
  3. All retries are exhausted without a successful payment.
  4. 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

Via 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.
Via Hub To cancel a subscription

  1. Go to Billing > Billing 2.0 > Subscriptions.
  2. Click on the subscription ID to open the details page.
  3. Click on Cancel.
  4. Choose to cancel immediately or at the end of the billing period.
  5. Optionally, provide a cancellation comment.
  6. Click on Cancel subscription to confirm the cancellation.

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. Via 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.