Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Online payments
Products and prices
Invoicing
Subscriptions
    Overview
    How subscriptions work
    Recurring pricing models
    Get started
    Quickstart
    Integrate a SaaS business
    Embed a pricing table
    Design an integration
    Build a subscriptions integration
    Migrate subscriptions to Stripe
    Billing resources
    Coupons
    Customers
    Subscriptions
    Subscription invoices
    Manage subscriptions
    Change subscriptions
      Upgrade and downgrade subscriptions
      Cancel subscriptions
      Manage prorations
      Pause payment collection
      Share an update payment details link
      Manage pending updates
      Set billing cycles
      Customer credit balance
    Usage-based billing
    Use trial periods
    Set payment methods
    Subscriptions with multiple products
    Set subscription quantities
    Subscription webhooks
    Schedule subscriptions
    Tax
    Sales-led B2B billing
    Integrate with Salesforce
    Manage recurring revenue
    Revenue recognition
    Revenue recovery
    Subscription metrics
    Customer management
    Overview
    Set up the the no-code customer portal
    Set up the customer portal with the API
    Configure the customer portal
    Testing
    Test your integration
    Test clocks
    Strong Customer Authentication (SCA)
    Invoices API updates
Quotes
In-person payments
Multiparty payments
After the payment
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
Billing
·
HomePaymentsSubscriptionsChange subscriptions

Cancel subscriptions

Learn how to cancel existing subscriptions.

Customer portal

This guide describes how to use the Subscriptions API to manage customer subscriptions through your site.

You can also let customers manage their subscriptions, invoices, and billing information through the Stripe-hosted customer portal.

You can manually cancel your customers’ subscriptions through the Subscription API or the Dashboard. If you only want to stop the subscription temporarily, you can pause it.

Subscriptions are canceled automatically after up to four unsuccessful attempts to bill the customer. You can configure this in your subscription lifecycle settings. Read more about revenue recovery settings, like Smart Retries and configurable customer emails, in the guides.

Cancel subscriptions

Cancel subscriptions through the Dashboard or API:

To cancel a subscription using the Dashboard:

  1. From the customer account page or the subscription details page, click the overflow menu (

    ), then select Cancel subscription.

  2. Choose when to end the subscription: immediately, at the end of the period, or on a custom day.

  3. Choose to provide a refund for a prorated amount, refund the last payment in full, or provide no refund. Learn more about prorations and refunds.

  4. After all settings are finalized, click Cancel subscription.

By default, the cancellation takes effect immediately. As soon the subscription cancels, no further invoices are generated for it.

Prorating and usage-based billing

If the subscription’s part way through a paid billing period, you can prorate the cancellation by passing the prorate parameter.

When you prorate a cancellation you can optionally invoice for:

  • Outstanding prorations
  • Metered usage

If you don’t prorate the subscription, all metered usage is discarded and the customer does not receive any credit for any potential prorations.

Cancel at end of cycle

If you instead want to cancel the subscription at the end of the current billing period (that is, for the duration of time the customer has already paid for), update the subscription with a cancel_at_period_end value of true:

Command Line
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -X "POST" \ -d "cancel_at_period_end"=true

You can reactivate subscriptions scheduled for cancellation (with the cancel_at_period_end parameter) by updating cancel_at_period_end to false. You can reactivate the subscription at any point up to the end of the period.

Automatically canceling after a dispute

This feature is only supported for disputed credit and debit card payments opened in the full amount.

When a customer disputes a charge for a subscription, the subscription continues to cycle, which can create more disputed charges. You can change this behavior in the Stripe Dashboard so that subscriptions are canceled instead. Under Manage disputed payments, select cancel the subscription immediately without prorating or cancel the subscription at the end of the period. It takes about one hour for changes to the subscription to take effect.

If you choose to cancel immediately, the subscription cancels immediately without any prorating. A canceled subscription can’t be restarted, so you must create a new one for the customer if you want to continue billing them.

If you choose to cancel at the end of the period, cancel_at_period_end is set to true and the subscription cancels at the end of the current billing period. This allows you some time to work through the dispute process before the cancellation occurs.

For subscriptions managed with schedules, the subscription is first released from the schedule and then canceled. This means the rest of the scheduled changes won’t take effect.

Invoice items and usage

When a subscription has pending invoice items you’ve created, the customer may still be billed for those if the cancellation is set to include a final invoice or there is another subscription active on the customer. To avoid this, manually delete the invoice items.

Similarly, any usage reported during the billing period bills at the end of the period. To avoid a final charge for usage, update the subscription and remove the metered price 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.

Canceling a subscription causes all open and draft invoices for that subscription to have their auto_advance property set to false. This occurs to prevent unexpected automatic payment attempts and reminder emails. This effectively pauses automatic collection for these invoices. You can still manually attempt to collect payment and manually send emails.

Cancellation events

Stripe sends a customer.subscription.deleted event when a customer’s subscription is canceled immediately. If the customer.subscription.deleted event’s request property isn’t 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 (that is, by setting cancel_at_period_end to true), 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 by updating cancel_at_period_end to true, and the subscription hasn’t yet reached the end of the billing period, it can be reactivated. Subscriptions canceled immediately, however, can’t be reactivated. To reactivate the subscription, update the subscription, setting the value of cancel_at_period_end to false.

Command Line
# Retrieve the subscription: curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: # Update the subscription using retrieved ID: curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "cancel_at_period_end"="false" \ -d "proration_behavior"="create_prorations" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f"

This prevents the subscription from canceling at the end of the billing period. You can also use the Dashboard’s Reactivate Subscription option.

Prior to version 2018-02-28, any parameter sent to the Update Subscription API would automatically reactivate a subscription.

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 (for example, to maintain the old billing cycle).

See also

  • Using trial periods
  • Update subscription
  • Cancel subscription
Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Cancel subscriptions
Invoice items and usage
Cancellation events
Reactivating canceled subscriptions
See also
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$