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.
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 USD per month, the following code switches the customer to a pro-monthly subscription at 30 USD per month:
If both prices have the same billing periods—combination of
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).
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
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
always_invoice, which will calculate the proration and then immediately generate an invoice after making the switch. You can combine this behavior with pending updates so that the subscription is only updated if payment succeeds on the new invoice.