Canceling and Pausing Subscriptions

    Learn how to outright cancel or virtually pause existing subscriptions.

    By default, a subscription continues (and continues billing the customer) until cancellation. As configured in your subscription lifecycle settings, a subscription may cancel automatically after up to four unsuccessful attempts to the bill the customer. 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_49ty4767H20z6a \
       -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_49ty4767H20z6a')
    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_49ty4767H20z6a')
    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_49ty4767H20z6a');
    $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 = Subscription.retrieve("sub_49ty4767H20z6a");
    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
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    stripe.subscriptions.del('sub_49ty4767H20z6a');
    
    // 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, _ := sub.Cancel("sub_49ty4767H20z6a", nil)
    
    // 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
    StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    var service = new StripeSubscriptionService();
    StripeSubscription subscription = service.Cancel("sub_49ty4767H20z6a");
    

    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 paid for the entire billing period and the subscription was canceled part-way through, the customer is not credited a refund automatically by Stripe. Note that, for metered plans, all reported usage is discarded.

    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_49ty4767H20z6a \
       -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_49ty4767H20z6a')
    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_49ty4767H20z6a')
    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_49ty4767H20z6a');
    $subscription->cancel(['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> params = new HashMap<>();
    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_49ty4767H20z6a', {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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.SubscriptionCancelParams{
      AtPeriodEnd: stripe.Bool(true),
    }
    subscription, _ := sub.Cancel("sub_49ty4767H20z6a", 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
    StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    var service = new StripeSubscriptionService();
    StripeSubscription subscription = service.Cancel("sub_49ty4767H20z6a", true);
    

    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. Any metered usage is charged for in a final invoice once the subscription cancels at the end of the billing period.

    Invoice items and usage

    When a subscription has pending invoice items you’ve created, the customer is still billed for those even after the subscription is canceled. To avoid that final charge, manually delete the invoice items.

    Similarly, any usage reported during the billing period is billed at the end of the period. To avoid a final charge for usage, update the subscription and remove the metered plan using the clear_usage parameter.

    If you set the subscription to cancel at period end, any pending prorations are left in place and still collected at the end of the period. If you cancel the subscription before the end of the period, invoice items will remain—and won’t be processed unless you specifically generate an invoice with them.

    By default, all unpaid invoices for the customer are closed upon subscription cancellation. This prevents unexpected payment retries once the customer has canceled a subscription. You can still reopen the invoices manually after subscription cancellation to proceed with automatic retries. You can also re-attempt payments yourself on all unpaid invoices before canceling the subscription.

    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, however, cannot. To reactivate the subscription, update the subscription, setting the value of cancel_at_period_end to false.

    # Retrieve the subscription:
    curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
    # Update the subscription using retrieved ID:
    curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d cancel_at_period_end=false \
       -d items[0][id]=si_09IkI4u3ZypJUk5onGUZpe8O \
       -d items[0][plan]=plan_CBb6IXqvTLXp3f
    
    # 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_49ty4767H20z6a')
    subscription.cancel_at_period_end = false
    subscription.items = [{
        id: subscription.items.data[0].id,
        plan: 'plan_CBb6IXqvTLXp3f',
    }]
    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_49ty4767H20z6a')
    stripe.Subscription.modify('sub_49ty4767H20z6a',
      cancel_at_period_end=False,
      items=[{
        'id': subscription['items']['data'][0].id,
        'plan': 'plan_CBb6IXqvTLXp3f',
      }]
    )
    
    // 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_49ty4767H20z6a');
    \Stripe\Subscription::update('sub_49ty4767H20z6a', [
      'cancel_at_period_end' => false,
      'items' => [
            [
                'id' => $subscription->items->data[0]->id,
                'plan' => 'plan_CBb6IXqvTLXp3f',
            ],
        ],
    ]);
    
    // 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> item = new HashMap<>();
    item.put("id", subscription.getSubscriptionItems().getData().get(0).getId());
    item.put("plan", "plan_CBb6IXqvTLXp3f");
    
    Map<String, Object> items = new HashMap<>();
    items.put("0", item);
    
    Map<String, Object> params = new HashMap<>();
    params.put("cancel_at_period_end", false);
    params.put("items", items);
    
    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");
    
    const subscription = await stripe.subscriptions.retrieve('sub_49ty4767H20z6a');
    stripe.subscriptions.update('sub_49ty4767H20z6a', {
      cancel_at_period_end: false,
      items: [{
        id: subscription.items.data[0].id,
        plan: 'plan_CBb6IXqvTLXp3f',
      }]
    });
    
    // 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.Get("sub_49ty4767H20z6a", nil)
    params := &stripe.SubscriptionParams{
      CancelAtPeriodEnd: stripe.Bool(false),
      Items: []*stripe.SubscriptionItemsParams{
        {
          ID: stripe.String(subscription.Items.Values[0].ID),
          Plan: stripe.String("plan_CBb6IXqvTLXp3f"),
        },
      },
    }
    subscription, err = sub.Update("sub_49ty4767H20z6a", 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
    StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    var service = new StripeSubscriptionService();
    StripeSubscription subscription = service.Get("sub_49ty4767H20z6a");
    
    var items = new List<StripeSubscriptionItemUpdateOption> {
        new StripeSubscriptionItemUpdateOption {
            Id = subscription.Items.Data[0].Id,
            PlanId = "plan_CBb6IXqvTLXp3f",
        },
    };
    var options = new StripeSubscriptionUpdateOptions {
      CancelAtPeriodEnd = false,
      Items = items,
    };
    subscription = service.Update("sub_49ty4767H20z6a", options);
    

    This 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 does not natively support pausing a subscription. You can, however, cancel the current subscription and recreate it later when it is time to start billing the customer again. There are also several alternative approaches that you may wish to consider:

    • To keep the subscription effectively active but no longer billing the customer, you can apply a 100% off coupon that lasts forever. Later remove the coupon when it’s time to begin billing again.
    • You can move the customer to a free plan and then resubscribe them to the paid plan later.
    • You can use a trial period to change the billing cycle.

    Next steps

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