Canceling and Pausing Subscriptions

    Learn how to outright cancel or virtually pause existing subscriptions. If you need help after reading this, search our documentation or check out answers to common questions. You can even chat live with other developers in #stripe on freenode.

    By default, a subscription continues, and the customer continues to be billed, until it’s canceled. Subscriptions may be automatically canceled due to a combination of too many failed payments and your subscription settings. But you can also cancel subscriptions yourself, either through the API or the Dashboard.

    Canceling subscriptions

    Subscriptions can be canceled through the API:

    curl https://api.stripe.com/v1/subscriptions/sub_5aR9kvK8NAwzIU \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -X 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.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
      }
    );
    // 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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    subscription, err := sub.Cancel("sub_5aR9kvK8NAwzIU")

    By default, the cancellation takes effect immediately. Once a customer’s subscription is canceled, no further invoices are 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. To determine how much a customer is credited by canceling a subscription, use the proration preview concept, setting the quantity to 0 to replicate no subscription. The resulting preview reflects the unused portion of the subscription in the invoice items.

    If you’d like to refund money to the customer after canceling a subscription, refund the corresponding amount on a previous payment.

    If you instead want to cancel the subscription at the end of the current billing period (i.e., for the duration of time the customer has already paid for), provide an at_period_end value of true:

    curl https://api.stripe.com/v1/subscriptions/sub_5aR9kvK8NAwzIU \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -X DELETE \
       -d 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.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 = customer.getSubscriptions().retrieve("sub_3R3PlB2YlJe84a");
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("at_period_end", true);
    
    subscription.cancel(params);
    // 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
      }
    );
    // 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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.SubParams{
      EndCancel: true,
    }
    subscription, err := sub.Cancel("sub_5aR9kvK8NAwzIU", params)

    Note that when a subscription has been scheduled for cancellation using at_period_end, it can be reactivated at any point up to the end of the period with any update via the API or the Dashboard.

    Cancellation events

    Stripe sends a customer.subscription.deleted event when a customer’s subscription is canceled immediately (i.e., with at_period_end set to false, which is the default). If the customer.subscription.deleted event’s request property is not null, that indicates the cancellation was made by your request (as opposed to automatically based upon your subscription settings).

    If you instead cancel a subscription at the end of the billing period, a customer.subscription.updated event is immediately triggered. That event reflects 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 then occurs.

    Reactivating canceled subscriptions

    If a customer’s subscription is canceled with at_period_end set to true and it has not yet reached the end of the billing period, it can be reactivated. (Subscriptions canceled immediately cannot be.) To reactive the subscription, update the subscription, setting the plan to the same ID as the current plan.

    curl https://api.stripe.com/v1/subscriptions/sub_5aR9kvK8NAwzIU \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d plan=pro-monthly
    
    # 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_5aR9kvK8NAwzIU")
    subscription.plan = "pro-monthly"
    subscription.save
    
    # 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_5aR9kvK8NAwzIU")
    subscription.plan = "pro-monthly"
    subscription.save()
    
    // 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_5aR9kvK8NAwzIU");
    $subscription->plan = "pro-monthly";
    $subscription->save();
    
    // 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_5aR9kvK8NAwzIU");
    
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("plan", "pro-monthly");
    subscription.update(params);
    
    // 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.update("sub_5aR9kvK8NAwzIU", {
        plan: "pro-monthly",
      }, function(err, subscription) {
        // asynchronously called
      }
    );
    
    // 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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.SubParams{
      Plan: "pro-monthly",
    }
    subscription, err := sub.Update("sub_5aR9kvK8NAwzIU", params)
    

    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 in 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 action results in a new charge. You can override this behavior using the trial_end parameter so the customer isn’t immediately billed (e.g., to maintain the old billing cycle).

    Pausing a subscription

    Stripe’s subscriptions logic does not support true pausing of a subscription. However, there are ways to emulate this behavior:

    • To “pause” a subscription for a period and then automatically resume the subscription, use a trial period to change the billing cycle. You may or may not want to prorate the move, depending upon your business model.
    • To keep the subscription effectively active but no longer billing the customer, apply a 100% off coupon that lasts forever. Later remove the coupon when it’s time to begin billing again.
    • Similarly, you could move the customer to a free plan and then resubscribe them to the paid plan later. This approach allows you to easily track paused subscriptions.
    • Finally, the cleanest option is to cancel the current subscription and recreate it when it’s time to bill the customer again. This is the least hack-y of the solutions, but the customer doesn’t show as having a subscription during the “pause”.

    Next steps

    Congrats! You know more about canceling subscriptions. Some resources you might want to see next: