Upgrading and Downgrading Plans

    Learn how to change a customer’s subscription by upgrading or downgrading their plan.

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

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

    Switching plans

    Subscriptions can be changed by switching the plan to which a customer is subscribed or by changing the quantity of a plan. 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 the standard-monthly plan at $10 per month, the following code switches the customer to the pro-monthly plan (plan_CBb6IXqvTLXp3f) at $30/month:

    # 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);
    

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

    Stripe immediately attempts payment for these subscription changes:

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

    When billing is performed immediately, but the required payment fails, the subscription change request also fails—leaving the subscription unchanged. If billing is deferred and does not occur immediately, failure will not result in rolling back the change to the subscription.

    If you want the customer to immediately pay the price difference when switching to a more expensive plan on the same billing cycle, you need to 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:

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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