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. This video shows how subscription schedules work 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

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 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:

1. 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).

2. 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_phase, you can control how prorations are handled using the top-level proration_behavior parameter.

This parameter works similarly to the one in the Update a subscription API, and accepts the following values:

• (default) create_prorations: Generate proration adjustments for billing changes.
• none: No prorations are created for the update.
• always_invoice: Generate prorations and immediately finalize an 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_behavior 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_behavior on phases[1] determines how those prorations are handled when transitioning from phases[0] to phases[1]:

• (default) create_prorations: Generate pending invoice items for billing changes.
• none: No prorations are created when entering this phase.
• always_invoice: Generate prorations and immediately create an invoice when entering this phase.

If you need to change how a future phase transition handles prorations, update the proration_behavior setting on the future phase before it becomes active.

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. 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:

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.

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.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d schedule=
{{SUBSCRIPTION_SCHEDULE_ID}}

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.

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "schedule_details[phases][0][start_date]"=now \
  -d "schedule_details[phases][0][items][0][price]"=
{{PRICE_ID}} \
  -d "schedule_details[phases][0][items][0][quantity]"=1 \
  -d "schedule_details[phases][0][iterations]"=12

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 state 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:

1. The phase that just ended and had two subscription items
2. 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_settings:

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.