Canceling and Pausing Subscriptions

Existing subscriptions can be outright canceled or simply paused. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

Subscriptions can be canceled through the API like this:

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = Stripe::Subscription.retrieve("sub_3R3PlB2YlJe84a")
subscription.delete

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = stripe.Subscription.retrieve("sub_3R3PlB2YlJe84a")
subscription.delete()

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$subscription = \Stripe\Subscription::retrieve("sub_3R3PlB2YlJe84a");
$subscription->cancel();

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Subscription subscription = customer.getSubscriptions().retrieve("sub_3R3PlB2YlJe84a");
subscription.cancel(null);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.subscriptions.del(
  "sub_3R3PlB2YlJe84a",
  function(err, confirmation) {
    // asynchronously called
  }
);

By default, the cancellation takes effect immediately. Once a customer’s subscription is canceled, no further invoices will be generated for that subscription. If the customer had paid for the entire billing period and the subscription was canceled part-way through the period, the customer is not credited a refund automatically by Stripe.

If you would like to cancel the subscription immediately, but keep the subscription active until the end of the billing period (e.g., through the time the customer has already paid for), provide an at_period_end value of true:

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = Stripe::Subscription.retrieve("sub_3R3PlB2YlJe84a")
subscription.delete(:at_period_end => true)

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = stripe.Subscription.retrieve("sub_3R3PlB2YlJe84a")
subscription.delete(at_period_end=True)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$subscription = \Stripe\Subscription::retrieve("sub_3R3PlB2YlJe84a");
$subscription->cancel(array('at_period_end' => true));

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Subscription subscription = Subscription.retrieve("sub_49ty4767H20z6a");

Map<String, Object> subscriptionParams = new HashMap<String, Object>();
subscriptionParams.put("at_period_end", true);

subscription.cancel(subscriptionParams);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.subscriptions.del(
  "sub_3R3PlB2YlJe84a",
  { at_period_end: true },
  function(err, confirmation) {
    // asynchronously called
  }
);
  • Stripe sends out a customer.subscription.deleted event when a customer’s subscription is canceled immediately.
  • A customer.subscription.updated event is immediately triggered if you cancel a subscription at the end of the billing period instead, reflecting the change in the subscription’s cancel_at_period_end value. When the subscription is actually canceled at the end of the period, a customer.subscription.deleted event will occur.

Reactivating Canceled Subscriptions

If a customer’s subscription has been canceled with at_period_end set to true and it has not yet reached the end of the billing period, update the subscription and set the plan to the same ID as the current plan. This updates the subscription’s cancel_at_period_end to false and prevents the subscription from canceling at the end of the billing period. You can also use the Reactivate Subscription option from the Dashboard.

If the cancellation has already been processed and the subscription is no longer active, a new subscription is needed for the customer. Keep in mind that Stripe immediately starts your customer’s subscription under a new billing cycle, so this result in a new charge. You can override this behavior by using the trial_end parameter so the customer isn’t immediately billed (e.g., to maintain the old billing cycle).

Pausing a Subscription

If you want to suspend a subscription and resume it at a later date, simply cancel the customer’s subscription so that no further billing will take place. When the customer is ready to resume their subscription, reactivate the canceled subscription, making sure that the trial period is set to end on the day their billing should resume.

Next steps