Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    How subscriptions work
    Quickstart
    Use cases
    Build your integration
    Subscription features
      Subscription invoices
      Subscription schedules
      Subscription pricing
      Recurring pricing models
      Embed a pricing table
      Start subscriptions
      Set quantities
      Set billing cycles
      Backdate subscriptions
      Subscribe to multiple items
      Set trial periods
      Apply coupons
      Migrate subscriptions to Stripe
      How credit prorations are calculated
      Subscription payments
      Subscription payment methods
      Integrate with third-party payment processing
      Collection methods
      Strong Customer Authentication (SCA)
      Manage subscriptions
      Modify subscriptions
        Change prices
        Cancel subscriptions
        Pause payment collection
        Manage prorations
      Manage pending updates
    Entitlements
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Revenue recognition
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptionsSubscription featuresModify subscriptions

Change the price of existing subscriptions

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

Customer portal

This guide focuses on using the Subscriptions API to manage customer subscriptions.

You can also implement the customer portal to provide a Stripe-hosted Dashboard where customers can manage their subscriptions and billing details.

When a customer changes their subscription, you must change the subscription item to reflect the new selection. For example, a customer might upgrade to a premium tier or downgrade to a basic tier, prompting you to replace the underlying price of that subscription item. You can do this using a few different methods.

Retrieve the identifiers

Regardless of the method you choose, you need to provide identifiers for the objects you’re updating. Use the list subscriptions method with a relevant filter (such as the customer ID) to find the subscription and item to update.

Command Line
cURL
curl -G https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d customer={{CUSTOMER_ID}}

The returns the set of subscriptions for the specified customer, from which you can retrieve the subscription ID (id), any subscription item IDs (items.data.id) and the subscription items price ID (items.data.price.id).

Retrieve subscriptions response sample
{ "object": "list", "url": "/v1/subscriptions", "has_more": false, "data": [ { "id": "su_1NXPiE2eZvKYlo2COk9fohqA", "object": "subscription", "application": null, "application_fee_percent": null, "automatic_tax": { "enabled": false }, "items": { "object": "list", "data": [ { "id": "si_OK3pbS1dvdQYJP", "object": "subscription_item", "billing_thresholds": null, "created": 1690208774, "metadata": {}, "price": { "id": "price_1NOhvg2eZvKYlo2CqkpQDVRT", "object": "price" } } ] } } ] }

Update the subscription

Update a subscription including the following parameters:

  • item ID: You must specify the subscription item to replace the current price with the new price. Otherwise, updating the subscription with a new price adds a new subscription item so both prices are active for the subscription.
  • item price: Provide the identifier for the replacement price.
  • item quantity: Updating a subscription price automatically reverts the quantity to the default value of 1. If the existing subscription quantity is anything other than 1 and you want to preserve that value, you must include it in the update.
Command Line
cURL
curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][id]"={{SUB_ITEM_ID}} \ -d "items[0][price]"={{NEW_PRICE_ID}}

Common mistake

You must specify the subscription item to replace the current price with the new price. Failing to do so results in adding the new price so both prices are active for the subscription.

Alternatively, you can delete the current subscription item and create a new subscription item with the updated price.

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][id]"={{SUB_ITEM_ID}} \ -d "items[0][deleted]"=true \ -d "items[1][price]"={{NEW_PRICE_ID}}

Update the subscription item

Update a subscription using the following parameter:

  • item price: Provide the identifier for the replacement price.
  • item quantity: Updating a subscription price automatically reverts the quantity to the default value of 1. If the existing subscription quantity is anything other than 1 and you want to preserve that value, you must include it in the update.

Use this option if you don’t need to make any other changes at the subscription level.

Command Line
cURL
curl https://api.stripe.com/v1/subscription_items/si_xxxxxxxxx \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d price={{NEW_PRICE_ID}}

Billing periods

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 doesn’t 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).

Subscription schedules

If you’re changing a subscription at the end of its billing cycle, consider using a subscription schedule to manage the transition. When using subscription schedules, be sure to follow best practices to prevent unexpected subscription overwrites.

Metered billing with Billing Meters

Details on mid-cycle updates for prices attached to a Billing Meter are described in the pricing models section. Passing clear_usage when updating a price with a Billing Meter has no effect.

Metered billing with Usage Records Legacy

If you have a metered price backed by legacy usage records and update to a new usage records price, the usage is transferred to the new price.

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][id]"={{SUB_ITEM_ID}} \ -d "items[0][price]"={{NEW_PRICE_ID}} \ -d "items[0][clear_usage]"=true

Proration

Changing a subscription often results in a proration to apply the new price to the remaining days in the billing period. You can prepare your customer for any additional expense resulting from a price change by previewing a proration. Alternatively, you can disable prorations.

Immediate payment

Stripe immediately attempts payment for these subscription changes:

  • From a subscription that doesn’t require payment (for example, 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 succeeds and the subscription transitions to past_due.

To bill a customer immediately for a change to a subscription on the same billing cycle, set proration_behavior to always_invoice. This calculates the proration, then immediately generates an invoice after making the switch. Combine this setting with pending updates so the subscription doesn’t update unless payment succeeds on the new invoice.

Credits for downgrades

When invoicing immediately for a downgrade, the customer might be owed a credit, which is added to their credit balance to be applied to future invoices. To refund your customer, issue refunds and then adjust their account balance back to zero. Learn more about customer refunds on our dedicated support page.

Handling zero-amount prices and quantities

If you’ve subscribed a customer to a zero-amount price (for example, as a trial), changing the price to a non-zero amount generates an invoice and resets the billing period to the date of the change.

If you’ve subscribed a customer to a price with a non-zero amount and a zero-amount quantity, changing the quantity to a non-zero amount does not generate an invoice or reset the billing period.

See also

  • Billing cycle
  • Canceling and pausing
  • Update Subscription API
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc