# Subscription schedules use cases

Learn how to use subscription schedules for common subscription scenarios.

Review these use cases to understand how to use [subscription schedules](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) to automate subscription changes in the Dashboard or API. Learn how to schedule start dates, switch subscription tiers, adjust quantities, and apply temporary discounts.

The examples use Typographic, a fictional font company that offers two monthly subscription options: Basic and Premium. Basic provides access to a standard font library, while Premium includes an expanded font library.

The Dashboard examples use **Forever** for the final phase to keep billing with that phase’s configuration. Setting a finite end date on the final phase in the Dashboard cancels the subscription at that date. To release a schedule after a fixed duration without canceling the subscription, use the API with `end_behavior=release`.

Create or select a customer and monthly recurring prices for the Basic and Premium tiers before creating a subscription. Replace the example price IDs and timestamps with your own.

If you represent your customers as customer-configured [Account](https://docs.stripe.com/api/v2/core/accounts/object.md) objects instead of [Customer](https://docs.stripe.com/api/customers/object.md) objects, replace the `customer` parameter in these code examples with the `customer_account` parameter. For more details, see [Represent customers using Account objects](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md).

## Start a subscription in the future 

Typographic starts new Basic subscriptions on the first day of the next month.

#### API

Set [start_date](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-start_date) to a future Unix timestamp. Stripe creates the subscription when that date arrives.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=1690873200 \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_BASIC}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=12"
```

#### Dashboard

1. Open the [subscription editor](https://dashboard.stripe.com/subscriptions?create=subscription), select the customer, and add the monthly Basic price with a quantity of 1.
2. Under **Duration**, select the start date and choose **1st of next month**.
3. Select **Forever** as the end date to keep the subscription active.
4. Click **Schedule subscription**.

## Backdate a subscription 

When customers subscribe to the Premium plan, Typographic backdates their subscriptions to the first day of the current month. Backdating allows you to charge for time in the past. Your application controls when customers can access the fonts.

#### API

Set [start_date](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-start_date) to a past Unix timestamp to create the subscription immediately and bill for the elapsed time. The 12-month phase in this example must end in the future. Choose a start date less than 12 months ago, such as the first day of the current month.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=1688194800 \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_PREMIUM}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=12"
```

#### Dashboard

1. Open the [subscription editor](https://dashboard.stripe.com/subscriptions?create=subscription), select the customer, and add the monthly Premium price with a quantity of 1.
2. Under **Duration**, select the start date and choose the first day of the current month.
3. Select **Forever** as the end date to keep the subscription active.
4. Review the proration settings and invoice preview for the elapsed time, then create the subscription.

## Add a schedule to an existing subscription 

Typographic might discover that some of its original customers are on subscriptions without schedules.

#### API

Pass the existing subscription ID in [from_subscription](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-from_subscription) instead of supplying `customer`, `start_date`, or `phases`. Stripe creates a schedule with one phase based on the subscription’s current billing period and configuration. Creating the schedule doesn’t create proration invoice items during the migration.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "from_subscription={{SUBSCRIPTION_ID}}"
```

#### Dashboard

Follow the [Dashboard update instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#updating) to add a future change. The editor creates the schedule when you save the scheduled changes.

To change plans at the end of the current billing period, see [Schedule an upgrade or downgrade for an existing subscription](https://docs.stripe.com/billing/subscriptions/subscription-schedules/use-cases.md#changing-subscriptions).

## Upgrade subscriptions 

Typographic offers an option to start with a Basic subscription for one month, then automatically upgrade to Premium. Customers can try the standard font library before switching to the expanded library.

#### API

Set the first phase’s [duration](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-duration) to one month. In the second phase’s [items](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-items), replace the Basic price with the Premium price.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_BASIC}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=1" \
  -d "phases[1][items][0][price]={{PRICE_PREMIUM}}" \
  -d "phases[1][items][0][quantity]=1" \
  -d "phases[1][duration][interval]=month" \
  -d "phases[1][duration][interval_count]=11"
```

#### Dashboard

Follow the [Dashboard creation instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#managing) with these phase settings:

1. **First phase**: Add the monthly Basic price with quantity **1** for one month.
2. **Second phase**: Replace the Basic price with the monthly Premium price with quantity **1**, and select **Forever** as the end date.

## Downgrade subscriptions 

Typographic also offers an option to start with a Premium subscription for one month, then downgrade to Basic. Customers can try the expanded font library before deciding whether the standard library meets their needs.

#### API

Include the Premium price in the first phase’s [items](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-items) for one month. Include only the Basic price in the second phase’s `items` for 11 months.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_PREMIUM}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=1" \
  -d "phases[1][items][0][price]={{PRICE_BASIC}}" \
  -d "phases[1][items][0][quantity]=1" \
  -d "phases[1][duration][interval]=month" \
  -d "phases[1][duration][interval_count]=11"
```

#### Dashboard

Follow the [Dashboard creation instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#managing) with these phase settings:

1. **First phase**: Add the monthly Premium price with quantity **1** for one month.
2. **Second phase**: Replace the Premium price with the monthly Basic price with quantity **1**, and select **Forever** as the end date.

## Schedule an upgrade or downgrade for an existing subscription 

A Typographic customer with a Premium subscription wants to downgrade to Basic at the end of the current billing period.

#### API

Use two requests to schedule the downgrade:

1. Create a subscription schedule from the subscription by passing the subscription ID to [from_subscription](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-from_subscription). Stripe creates a schedule with a phase that matches the subscription’s current billing period and configuration.
2. Update the schedule by passing the current phase and adding a second phase with the Basic price. The second phase starts automatically when the current phase ends.

The following end-to-end example schedules the downgrade for a subscription with one item and no other phase-level settings. To schedule an upgrade, specify the upgraded price in the second phase.

Include all items and settings from the current phase in the update, such as discounts, metadata, tax rates, and trial settings. Stripe unsets omitted parameters. When you update a schedule, pass all current and future phases that you want to keep.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

# Create a subscription schedule with the existing subscription
schedule = client.v1.subscription_schedules.create({
  from_subscription: 'sub_ERf72J8Sc7qx7D',
})

# Update the schedule with the new phase
client.v1.subscription_schedules.update(
  schedule.id,
  {
    phases: [
      {
        items: [
          {
            price: schedule.phases[0].items[0].price,
            quantity: schedule.phases[0].items[0].quantity,
          },
        ],
        start_date: schedule.phases[0].start_date,
        end_date: schedule.phases[0].end_date,
      },
      {
        items: [
          {
            price: '{{PRICE_BASIC}}',
            quantity: 1,
          },
        ],
        duration: {
          interval: 'month',
          interval_count: 1,
        },
      },
    ],
  },
)
```

#### Dashboard

Follow the [Dashboard update instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#updating) with these phase settings:

1. **Current phase**: Keep the Premium price until the end of the current billing period.
2. **Future phase**: Replace the Premium price with the Basic price and select **Forever** as the end date. Keep any unrelated items and quantities.

Review the phase’s proration settings before saving. To schedule an upgrade instead, use the Premium price in the future phase.

## Increase the quantity 

You can also schedule increases to the quantities on a subscription. This example starts with one Premium seat for one month. In the second phase, the quantity increases to 2 seats for 11 more months.

#### API

Keep the same price in both phases and change the item’s [quantity](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-items-quantity) from `1` in the first phase to `2` in the second phase.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_ID}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=1" \
  -d "phases[1][items][0][price]={{PRICE_ID}}" \
  -d "phases[1][items][0][quantity]=2" \
  -d "phases[1][duration][interval]=month" \
  -d "phases[1][duration][interval_count]=11"
```

#### Dashboard

Follow the [Dashboard creation instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#managing) with these phase settings:

1. **First phase**: Add the monthly Premium price with quantity **1** for one month.
2. **Second phase**: Keep the Premium price, change its quantity to **2**, and select **Forever** as the end date.

## Use coupons 

Typographic occasionally runs subscription specials. This example starts the customer on the Basic subscription at 50% off for six months. Use a 50%-off coupon with a [duration](https://docs.stripe.com/billing/subscriptions/coupons.md#coupon-duration) of `forever` so the discount applies to all six monthly invoices. The schedule removes the coupon from the subscription in the second phase for the remaining six months.

#### API

Use the ID of a 50%-off coupon in the first phase’s [discounts](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-discounts). Omit `discounts` from the second phase.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_ID}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=6" \
  -d "phases[0][discounts][0][coupon]={{COUPON_ID}}" \
  -d "phases[1][items][0][price]={{PRICE_ID}}" \
  -d "phases[1][items][0][quantity]=1" \
  -d "phases[1][duration][interval]=month" \
  -d "phases[1][duration][interval_count]=6"
```

#### Dashboard

Create or select a 50%-off coupon, then follow the [Dashboard creation instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#managing) with these phase settings:

1. **First phase**: Add the monthly Basic price and the coupon for six months.
2. **Second phase**: Keep the Basic price, remove the coupon, and select **Forever** as the end date.

## Change tax rates 

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

#### API

Set [tax_rates](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-items-tax_rates) on the item in each phase using your manual tax rate IDs. This example doesn’t use automatic tax calculation.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]={{PRICE_ID}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][items][0][tax_rates][0]=txr_2J8lmBBGHJYyuUJqF6QJtaAA" \
  -d "phases[0][duration][interval]=month" \
  -d "phases[0][duration][interval_count]=1" \
  -d "phases[1][items][0][price]={{PRICE_ID}}" \
  -d "phases[1][items][0][quantity]=1" \
  -d "phases[1][items][0][tax_rates][0]=txr_2J8lmBBGHJYyuUJqF6QJtbBB" \
  -d "phases[1][duration][interval]=month" \
  -d "phases[1][duration][interval_count]=11"
```

#### Dashboard

Create or select the two manual tax rates, then follow the [Dashboard creation instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#managing) with these phase settings instead of using automatic tax calculation:

1. **First phase**: Add the monthly price and apply the first manual tax rate to the product for one month.
2. **Second phase**: Keep the same price, replace the product’s manual tax rate with the second tax rate, and select **Forever** as the end date.

## Release a subscription from a schedule 

Pass the schedule ID, not the subscription ID, to the [release API](https://docs.stripe.com/api/subscription_schedules/release.md). You can release a schedule with status `not_started` or `active`. Releasing removes the schedule and its remaining phases without canceling an existing subscription or creating one for a schedule that hasn’t started.

```curl
curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/release \
  -u "<<YOUR_SECRET_KEY>>:"
```

## 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_started` or `active`.

#### API

Pass the schedule ID to the [cancellation endpoint](https://docs.stripe.com/api/subscription_schedules/cancel.md):

```curl
curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/cancel \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### Dashboard

For a schedule with an active subscription, open the subscription from the [Subscriptions](https://dashboard.stripe.com/subscriptions) page and select **Cancel subscription**. Choose to cancel immediately, review the final invoice and proration options, and confirm the cancellation. This also cancels the attached schedule.

For a schedule that hasn’t started, open the scheduled subscription in the Dashboard, select **Delete subscription**, and confirm. This cancels the schedule before it creates a subscription.

## Reset the billing cycle anchor 

Typographic bills its long-time Basic customers on whichever day of the month they originally subscribed. This day is their billing cycle anchor.

If these customers transition to Premium, Typographic schedules their transition date for the first day of the following month and resets the billing cycle anchor to that same date.

After scheduling the transition, open the subscription in the Dashboard and check the upcoming invoice date. With the billing cycle anchor reset, Stripe schedules the invoice for the first day of the month, when the Premium phase starts.

#### API

Set [billing_cycle_anchor](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-billing_cycle_anchor) to `phase_start` on the Premium phase to bill when that phase starts. Without this setting, the subscription keeps its existing billing cycle anchor. Replace the first phase’s [end_date](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-end_date) with the first day of next month.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d "phases[0][items][0][price]={{PRICE_BASIC}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][end_date]=1690873200" \
  -d "phases[1][items][0][price]={{PRICE_PREMIUM}}" \
  -d "phases[1][items][0][quantity]=1" \
  -d "phases[1][duration][interval]=month" \
  -d "phases[1][duration][interval_count]=11" \
  -d "phases[1][billing_cycle_anchor]=phase_start"
```

#### Dashboard

1. Follow the [Dashboard update instructions](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md?dashboard-or-api=dashboard#updating) to keep the Basic price in the current phase until the first day of next month.
2. Add a future phase with the Premium price instead of the Basic price and select **Forever** as its end date.
3. In that future phase, under **Billing cycle details**, select **Reset billing cycle anchor to now**. For a future phase, this resets the anchor when the phase starts, not when you save the schedule.
4. Review the proration settings, save the phase, and save the scheduled changes.

The reset option isn’t shown when the phase already starts on a billing cycle boundary.

## Installment plans 

Use a subscription with a fixed end date to collect a set number of monthly payments.

#### API

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:

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d unit_amount=100000 \
  -d currency=usd \
  -d "product={{PRODUCT_ID}}" \
  -d "recurring[interval]=month"
```

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.

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d start_date=now \
  -d end_behavior=cancel \
  -d "phases[0][items][0][price]={{PRICE_ID}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][iterations]=6"
```

#### Customers v1

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=cancel \
  -d "phases[0][items][0][price]={{PRICE_ID}}" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][iterations]=6"
```

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_behavior` determines what happens to the subscription after the last iteration is complete. In an installment plan, the subscription isn’t needed anymore so `end_behavior` 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_data` to create a single-use price. This example creates a 500 USD price, and charges monthly for 6 months:

#### Accounts v2

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer_account={{CUSTOMERACCOUNT_ID}}" \
  -d start_date=now \
  -d end_behavior=cancel \
  -d "phases[0][items][0][price_data][currency]=usd" \
  -d "phases[0][items][0][price_data][product]={{PRODUCT_ID}}" \
  -d "phases[0][items][0][price_data][recurring][interval]=month" \
  -d "phases[0][items][0][price_data][unit_amount]=50000" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][iterations]=6"
```

#### Customers v1

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d start_date=now \
  -d end_behavior=cancel \
  -d "phases[0][items][0][price_data][currency]=usd" \
  -d "phases[0][items][0][price_data][product]=prod_Hh99apo1OViyGW" \
  -d "phases[0][items][0][price_data][recurring][interval]=month" \
  -d "phases[0][items][0][price_data][unit_amount]=50000" \
  -d "phases[0][items][0][quantity]=1" \
  -d "phases[0][iterations]=6"
```

#### Dashboard

To collect six monthly payments of 1,000 USD:

1. Open the [subscription editor](https://dashboard.stripe.com/subscriptions?create=subscription) and select the customer.
2. Add a monthly recurring price of 1,000 USD with a quantity of 1.
3. Under **Duration**, set the start date and an end date six monthly billing cycles later. Don’t select **Forever**.
4. Review the schedule and create the subscription.

The subscription cancels at the end of the 6-month phase.