Upgrade and downgrade subscriptions

    Learn how to upgrade and downgrade subscriptions by changing the price.

    One way existing subscriptions can be modified is by upgrading or downgrading the underlying price. For example, a customer might want to switch from your basic offering to your pro offering, which is easily accomplished via an update subscription call.

    Changing a subscription often results in a proration. So that you can prepare your customer for any additional expense that comes with a price change, we provide a method of previewing a proration. Alternatively, you can choose to disable proration.

    Changing prices

    Subscriptions can be changed by switching the price that a customer is charged or by changing the quantity. Normally the result qualifies as either upgrading or downgrading the subscription, depending upon the price difference between the two subscriptions.

    Assuming a customer is currently subscribed to a basic-monthly subscription at $10 per month, the following code switches the customer to a pro-monthly subscription at $30 per month:

    # 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
    # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' subscription = Stripe::Subscription.retrieve('sub_49ty4767H20z6a') Stripe::Subscription.update( subscription.id, { cancel_at_period_end: false, proration_behavior: 'create_prorations', items: [ { id: subscription.items.data[0].id, price: 'price_CBb6IXqvTLXp3f' } ] } )
    # Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' subscription = stripe.Subscription.retrieve('sub_49ty4767H20z6a') stripe.Subscription.modify( subscription.id, cancel_at_period_end=False, proration_behavior='create_prorations', items=[{ 'id': subscription['items']['data'][0].id, 'price': 'price_CBb6IXqvTLXp3f', }] )
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); $subscription = \Stripe\Subscription::retrieve('sub_49ty4767H20z6a'); \Stripe\Subscription::update('sub_49ty4767H20z6a', [ 'cancel_at_period_end' => false, 'proration_behavior' => 'create_prorations', 'items' => [ [ 'id' => $subscription->items->data[0]->id, 'price' => 'price_CBb6IXqvTLXp3f', ], ], ]);
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; Subscription subscription = Subscription.retrieve("sub_49ty4767H20z6a"); SubscriptionUpdateParams params = SubscriptionUpdateParams.builder() .setCancelAtPeriodEnd(false) .setProrationBehavior(SubscriptionUpdateParams.ProrationBehavior.CREATE_PRORATIONS) .addItem( SubscriptionUpdateParams.Item.builder() .setId(subscription.getItems().getData().get(0).getId()) .setPrice("price_CBb6IXqvTLXp3f") .build()) .build(); subscription.update(params);
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); const subscription = await stripe.subscriptions.retrieve('sub_49ty4767H20z6a'); stripe.subscriptions.update('sub_49ty4767H20z6a', { cancel_at_period_end: false, proration_behavior: 'create_prorations', items: [{ id: subscription.items.data[0].id, price: 'price_CBb6IXqvTLXp3f', }] });
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" subscription, err := sub.Get("sub_49ty4767H20z6a", nil) params := &stripe.SubscriptionParams{ CancelAtPeriodEnd: stripe.Bool(false), ProrationBehavior: stripe.String(string(stripe.SubscriptionProrationBehaviorCreateProrations)), Items: []*stripe.SubscriptionItemsParams{ { ID: stripe.String(subscription.Items.Values[0].ID), Price: stripe.String("price_CBb6IXqvTLXp3f"), }, }, } subscription, err = sub.Update("sub_49ty4767H20z6a", params)
    // Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var service = new SubscriptionService(); Subscription subscription = service.Get("sub_49ty4767H20z6a"); var items = new List<SubscriptionItemOptions> { new SubscriptionItemOptions { Id = subscription.Items.Data[0].Id, Price = "price_CBb6IXqvTLXp3f", }, }; var options = new SubscriptionUpdateOptions { CancelAtPeriodEnd = false, ProrationBehavior = "create_prorations", Items = items, }; subscription = service.Update("sub_49ty4767H20z6a", options);

    If both prices have the same billing periods—combination of interval and interval_count, the subscription retains the same billing dates. If the prices have different billing periods, the new price is billed at the new interval, starting on the day of the change. For example, switching a customer from one monthly subscription to another does not change the billing dates. However, switching a customer from a monthly subscription to a yearly subscription moves the billing date to the date of the switch. Switching a customer from one monthly subscription to another monthly subscription while introducing a trial period also moves the billing date (to the conclusion of the trial).

    Immediate payment

    Stripe immediately attempts payment for these subscription changes:

    • From a subscription that doesn’t require payment (e.g., due to a trial or free subscription) to a paid subscription
    • When the billing period changes

    When billing is performed immediately, but the required payment fails, the subscription change request will succeed and the subscription will transition to past_due.

    If you want the customer to immediately pay the price difference when switching to a more expensive subscription on the same billing cycle, you can set proration_behavior to always_invoice, which will calculate the proration and then immediately generate an invoice after making the switch.

    Next steps

    You now know how to upgrade or downgrade a subscription. Some resources you might want to see next:

    Was this page helpful?

    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page