Subscription schedules
Learn about subscription schedules and how to use them.
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. This video shows how subscription schedules work in the Dashboard:
Subscription schedules in the Dashboard
For examples of how you can use subscription schedules, see Use cases.
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 reverts to the normal cost and the coupon is removed. Phases must be sequential, meaning only one phase can be active at a given time. You can have up to 10 phases.
Set the length of a phase 
You can set the length of a phase using the API or the Dashboard.
Transition to the next phase 
Phase transitions happen automatically after the end_
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 prorations to credit the user for unused items or time on the plan.
Proration behavior 
There are two different proration behavior settings that control how Stripe handles billing adjustments during subscription schedule changes:
Schedule update proration behavior: The top-level proration_behavior parameter controls how to handle prorations when updating a subscription schedule in a way that affects the current phase’s billing configuration (such as changing prices or quantities).
Phase transition proration behavior: Each phase has its own proration_behavior attribute that controls how Stripe handles prorations when transitioning to that phase.
Schedule update proration behavior
When you update a subscription schedule and change the billing configuration of the current_
, you can control how prorations are handled using the top-level proration_
parameter.
This parameter works similarly to the one in the Update a subscription API, and accepts the following values:
- (default)
create_
: Generate proration adjustments for billing changes.prorations none
: No prorations are created for the update.always_
: Generate prorations and immediately finalize an invoice.invoice
Changes to non-billing fields (like metadata) won’t generate prorations regardless of this setting.
Phase transition proration behavior
Each phase can define its own proration_
to control what happens when the subscription enters that phase. This setting applies specifically to prorations generated during phase transitions and is saved as a field on the phase.
For example, if phases[1]
increases the quantity from 1 to 3 when it starts, the proration_
on phases[1]
determines how those prorations are handled when transitioning from phases[0]
to phases[1]
:
- (default)
create_
: Generate pending invoice items for billing changes.prorations none
: No prorations are created when entering this phase.always_
: Generate prorations and immediately create an invoice when entering this phase.invoice
If you need to change how a future phase transition handles prorations, update the proration_
setting on the future phase before it becomes active.
Use trials 
You can add a trial period to the first phase of a subscription using the API or the Dashboard.
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
. The subscription’s cancel_on_date isn’t set until the subscription transitions into the final phase.
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 
This example demonstrates how to create 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_
set to charge_
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 approximately 1 hour after creation.
For example, when you create a subscription schedule with the collection method set to charge automatically and with start_
, this also creates a subscription and an invoice in the draft
status. You have 1 hour to edit the invoice. Later, the invoice auto-advances to open
or paid
status, depending on the outcome of the asynchronous payment attempt at finalization time.
Update subscription schedules 
You can only update the current and future phases on subscription schedules.
Preview an invoice
Use the schedule parameter in the create preview 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.
Additional considerations 
Subscription schedules generally follow the same restrictions as subscriptions, but also introduce some of their own restrictions. Additionally, the interaction between subscription schedules and subscriptions can produce unexpected behavior. Review the following sections to understand limitations, product behavior, and general best practices when using subscription schedules.
Restrictions 
- You can only define up to 10 current or future phases at a time on a subscription schedule. Past phases don’t count against this limit.
- Subscription schedule phases also follow the same restrictions as subscriptions when creating subscription schedule phases with multiple items.
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
Subscription updates when a schedule is attached 
Use subscription schedules to modify subscriptions automatically when time passes and the schedule’s next phase is entered. Some changes that you make directly to the subscription propagate to the subscription schedule’s phases, but some don’t. This means that any modifications you make directly to the subscription might be overwritten by the subscription schedule when the next phase is entered.
When scheduling changes to a subscription, follow these best practices:
- If a subscription has a subscription schedule attached, use the Subscription Schedule API to modify the subscription, instead of the Subscriptions API.
- Store the subscription schedule IDs alongside the subscription ID for future API updates. The subscription schedule ID returns when you use the API to create it or through the subscription_schedule.created webhook when Stripe creates it automatically, such as when a customer scheduled a downgrade in the Customer Portal.
- Discard the subscription schedule IDs when a subscription schedule is released. You can make changes to the subscriptions directly or create a new subscription schedule. The subscription schedule ID is returned when released with the API or through the subscription_schedule.released webhook event when the subscription schedule releases.
- Use the Dashboard to modify subscriptions, if possible, which automatically updates any attached subscription schedule.
Specifically, when you change any of the following subscription attributes directly on a subscription, this action might automatically create a new subscription schedule phase:
discounts
tax_
rates items
trial_
,end trial_
,settings trial_
start application_
fee_ percent add_
invoice_ items automatic_
tax
For example, consider a subscription with two items. The subscription has a subscription schedule attached with a single phase, mirroring the current status of the subscription. If you use the API to delete one of the items, this automatically splits the attached subscription schedule’s phase into two phases:
- The phase that just ended and had two subscription items
- The new phase that has just one item on the subscription
When subscription schedule phases automatically split, the following properties are copied from the current phase to the new phase:
proration_
behavior billing_
cycle_ anchor cancel_
at_ period_ end description
metadata
pause_
collection
Additionally, Stripe might copy the following top-level subscription attributes to the subscription schedule or its default_
:
Subscription attribute | Copied to new subscription schedule phase | Copied to subscription schedule default_ |
---|---|---|
coupon | ||
trial_ | ||
tax_ | ||
application_ | ||
discounts | ||
collection_ | ||
invoice_ | ||
default_ | ||
default_ | ||
transfer_ | ||
on_ | ||
currency | ||
add_ | ||
automatic_ | ||
items. | ||
billing_ |
Updates to subscription metadata
aren’t propagated to an attached subscription schedule.
Use cases
To understand subscription schedules, imagine a fictional newspaper company called The Pacific that offers two subscription options:
- Print, where customers receive the physical paper
- Digital, where customers get access to exclusive content on The Pacific’s website
Both subscriptions bill monthly. Browse possible options for subscription schedules below.
Start a subscription in the future
By default, new print subscriptions start on the first day of the next month. To accomplish this, set the start_
to a point in the future. The code below creates a subscription that starts in the future:
Backdate a subscription
When customers subscribe to the digital plan, The Pacific backdates their subscriptions to the first day of the current month. Backdating allows you to charge for time in the past and allows digital subscribers to access the website immediately.
Add a schedule to an existing subscription
The Pacific might discover that some of their original customers are on subscriptions without schedules. Because these subscriptions exist already, you can pass the subscription IDs in the from_
attribute to add a schedule. Passing the subscription IDs in this way creates a schedule with one phase that’s based on the current billing period of the subscription.
While adding these schedules, some customers decide to get a print subscription, so The Pacific adds a second phase to the schedule to start the print plan one month from now. The Upgrade subscriptions use case shows an example of this process.
Upgrade subscriptions
The Pacific offers an option to start with a print subscription for one month, then automatically add the digital option. Some customers prefer this because they can try the print publication first and then decide if they want to continue or cancel their subscription.
Downgrade subscriptions
The Pacific also offers an option to start a subscription with both the print and digital publications, and then downgrade to only the print publication for the rest of the subscription. Customers use this option to try both publications and see how they like them.
Change subscriptions
The Pacific offers two print subscription options: a basic option with advertisements or a premium option without advertisements. Some customers on the premium option want to change to the basic option at the next billing period. You can create a schedule using the existing subscription, and then update the schedule with the basic option with advertisements as a new phase.
Increase the quantity
You can also schedule increases to the quantities on a subscription. The schedule below starts with one instance of the digital publication for one month. In the second phase, the quantity is increased to 2 for 11 more months.
Use coupons
The Pacific occasionally runs subscription specials. The schedule below starts the customer on the print publication at 50% off for six months. The schedule removes the coupon from the subscription in the second phase for the remaining six months.
Change tax rates
The Pacific operates in several jurisdictions, and some have unique tax rates for subscription-based businesses. One of these jurisdictions requires two tax rates: one for the first month when a customer initially subscribes, and one for recurring billings.
Release a subscription from a schedule
You can release a subscription from a schedule if the status is not_
or active
. Releasing a subscription leaves it in place but removes the schedule and any remaining phases.
Cancel a schedule and subscription
If a subscription schedule has an active subscription, you can cancel it and its associated subscription immediately. You can only cancel a subscription schedule if its status is not_
or active
.
Reset the billing cycle anchor
The Pacific bills their long-time print customers on whichever day of the month they originally subscribed. This day is their billing cycle anchor.
If these customers transition to the digital edition, The Pacific schedules their transition date for the 1st day of the following month. They also reset the billing cycle anchor to that same date.
You can verify that the billing cycle anchor gets reset by creating a subscription using the sample code below. Look at the subscription in the Dashboard, and notice that the Upcoming Invoice is scheduled to bill the customer as soon as the digital subscription starts on the 1st.
To see what happens if you don’t reset the anchor, run the sample code again, but remove the line that sets the billing cycle anchor to phase_
. Without that line, the Upcoming Invoice in the Dashboard waits to bill the customer until a full month from today, despite the transition that occurs on the 1st.
Installment plans
Installment plans allow customers to make partial payments for a set amount of time until the total amount is paid. For example, when The Pacific buys new printing presses, they sell the used ones to other publications. Smaller publications rarely have enough funds to pay for a printing press upfront, so they pay using an installment plan instead.
For most presses, The Pacific charges 1,000 USD per month so a reusable price is created:
Depending on the make, model, and age of the printing press, The Pacific charges different amounts. This example charges 1,000 USD each month for 6 months, for a total of 6,000 USD.
The number of iterations
is multiplied by the price’s interval—6 monthly payments in this example—to determine the number of times the customer is charged. end_
determines what happens to the subscription after the last iteration is complete. In an installment plan, the subscription isn’t needed anymore so end_
is set to cancel
.
In rare cases, The Pacific charges less than the usual 1,000 USD per month. In these scenarios, they use price_
to create a single-use price. This example creates a 500 USD price, and charges monthly for 6 months: