Subscription schedules
Use subscription schedules to automate changes to subscriptions over time. You can create subscriptions directly through a schedule or you can add a schedule to an existing subscription. Use the phases attribute to define the changes you want to make to the subscription. After a schedule completes all of its phases, it completes based on its end_behavior.
Some changes you might want to schedule include:
- Starting a subscription on a future date
- Backdating a subscription to a past date
- Upgrading or downgrading a subscription
Subscription schedules are available in both the Stripe Billing Dashboard and the API. Here’s a quick video of how subscription schedules work in the Dashboard:
Subscription schedules in the Dashboard
The rest of this document explains subscription schedules in more detail. To see a list of examples, see the use cases page.
Phases
When creating a subscription schedule, use the phases attribute to define when changes occur and what properties of the subscription to change. For example, you might offer a coupon for 50% off for the first three months of a subscription. In this scenario, you’d create a subscription schedule where the first phase is three months long and contains the 50% off coupon. In the second phase, the subscription would be reverted to the normal cost and the coupon would be removed. Phases must be sequential, meaning only one phase can be active at a given time.
Set the length of a phase
The interval of a price determines how often to bill for a subscription. For example, a monthly interval is billed every month. Phases have an iterations attribute that you use to specify how long a phase should last. Multiply this value by the interval to determine the length of the phase. If a subscription schedule uses a price with a monthly interval and you set iterations=2
, the phase lasts for two months.
The end_date
of one phase has to be the start_date
for the next phase. Using iterations
automatically sets the start_date
and end_date
properly. You can set these values manually, but Stripe recommends using iterations
instead. Because manually setting the start and end dates is prone to errors, only use it for advanced use cases.
Transition to the next phase
Phase transitions happen automatically after the end_date
on a phase is reached. When a phase starts, Stripe updates the subscription based on the attributes of the next phase. You can optionally enable proration to credit the user for unused items or time on the plan.
Use trials
You can add trial periods by setting trial end on a phase. If you want the entire phase to be a trial, set the value of trial_end
to the same time as the end_date
of the phase. You can also set trial_end
to a time before the end_date
if you want to make only part of the phase a trial. When scheduling updates, you must specify the new trial_end
on each phase.
Complete a schedule
Subscription schedules end after the last phase is complete. At this point, the subscription is left in place and is no longer associated with the schedule. If you want to cancel a subscription after the last phase of a schedule completes, you can set end_behavior to cancel
.
Phase attribute inheritance
When a phase becomes active, all attributes set on the phase are also set on the subscription. After the phase ends, attributes remain the same unless the next phase modifies them, or if the schedule has no default setting. You can set some attributes on both schedules and phases. This includes:
If one of these attributes is defined on the schedule, it becomes the default for all phases. When the same property is defined on both the schedule and the phase, the phase attribute overrides the schedule attribute. This behavior is explained more below:
Schedule attribute present | Phase attribute present | Outcome |
---|---|---|
No | No | Defaults to the customer or account settings |
Yes | No | Schedule attribute set |
Yes | Yes | Phase attribute set |
No | Yes | Phase attribute set |
Use phase metadata
You can use subscription schedule phases to set metadata on the underlying subscription. This allows you to control the metadata on a subscription with scheduled updates.
Learn how to copy subscription metadata onto subscription invoices.
Create subscription schedules
The use cases page has more thorough examples but below is a basic example of creating a subscription schedule using a customer. Creating a schedule this way automatically creates the subscription as well.
Note
Unlike when you create a subscription directly, the first invoice of a subscription schedule with collection_method
set to charge_automatically
behaves like a recurring invoice and isn’t immediately finalized at the time the schedule’s subscription is created. The invoice begins in a draft
status and is finalized by Stripe about 1 hour after creation.
This means that, for example, creating a charge-automatically subscription schedule with start_date=now
also creates a subscription and an invoice in the draft
status. This gives you a 1-hour window to make edits to the invoice. Later, the invoice is auto-advanced into the open
or paid
status depending on the outcome of the asynchronous payment attempt at finalization time.
This schedule:
- Starts as soon as it’s created.
- Sets the subscription to one instance of the product at
price_1GqNdGAJVYItwOKqEHb
. - Goes through 12 iterations and then releases the subscription from the schedule.
You can also create subscription schedules by passing a subscription ID:
Creating a schedule this way uses attributes on the subscription to set attributes on the schedule.
Similar to other Stripe APIs, you can retrieve and update subscription schedules. You can also cancel and release them. Cancelling a subscription schedule cancels the subscription as well. If you only want to remove a schedule from a subscription, use the release call.
Create subscription schedules without code
You can create multi-phase subscription schedules without using code in the Stripe Billing subscription editor. To do so, follow these steps:
- In the Dashboard, open the subscription editor.
- Add a customer.
- Add a price to the product selection dropdown.
- Set a duration for the first phase of the subscription schedule.
- Click + Add phase.
- Select your next phase duration, or just forever to keep the subscription going.
- Make the required changes to your new phase. You can change the quantity, change the price, add or remove coupons, reset the billing cycle date, change proration behavior, or update metadata. If you change the metadata in a phase, it updates the subscription’s metadata when that phase activates.
- Save the new phase.
- Add any additional phases as needed.
- Create a subscription.
Update subscription schedules
You can only update the current and future phases on subscription schedules. You need to pass in all current and future phases when you update a subscription schedule. You also need to pass in any previously set parameters that you want to keep. Any parameters that were previously set are unset for the existing phase unless you pass those in the update request. You still receive information in the response about past phases.
You can include up to 10 current or future phases. Updating the active phase updates the underlying subscription as well. For example, this call maintains the existing start and end dates, but updates the quantity
to two:
You can also end the current phase immediately and start a new phase. This moves the active phase to the past and immediately applies the new phase to the subscription. The example below ends the current phase and starts a new phase:
To add additional phases to a subscription schedule, pass in the current phase, and then define your new phases:
Update subscription schedules without code
You can update existing subscriptions to have future subscription schedule phases using the Stripe Billing subscription editor. To do so, follow these steps:
- In the Dashboard, go to the Subscriptions page, select an existing subscription, and click Actions > Update subscription.
- Set a duration for the current phase of the subscription schedule by selecting an end date.
- Click +Add phase.
- Select your next phase duration, or just select forever to keep the subscription going.
- Make the required changes to your new phase. You can change the quantity, change the price, add or remove coupons, reset the billing cycle date, change proration behavior, or update metadata. If you change the metadata in a phase, it updates the subscription’s metadata when that phase activates.
- Save the new phase.
- Add any additional phases as needed.
- Create a subscription.
Preview an invoice
Use the schedule parameter in the upcoming invoice API to preview the next invoice for a subscription schedule.
Previewing schedule creation and updates
Use the parameters in schedule_details to preview creating or updating a subscription schedule. Pass an existing schedule to tell Stripe whether it’s a creation or an update.
Pass all of the current and future phases you’re previewing.
For example, the following code previews the first invoice for a subscription schedule with 1
phase that lasts for 12
billing periods.
Dashboard limitations
You can create and update subscription schedules without code in the Dashboard.
In the Dashboard, you can set the following settings globally across all phases, but not on a per phase basis:
- Billing thresholds
- Payment methods
- Invoice settings
- Subscription description
- Trial days (only works with the first phase)
The following parameters aren’t supported in the Dashboard:
- Subscription schedule metadata
- Phase item metadata
- Currency
- All Connect parameters