Billing
Start with a use case
Manage subscriptions
Add payment methods
Invoice customers
Revenue recognition
Sign in
Sign up
Support
Sign in
Billing
Additional features
Subscription schedules
HomePaymentsBillingAdditional features

Subscription Schedules API

Learn about the Subscription Schedules object and how to use it.

Subscription schedules are used 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

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.

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

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

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

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

Schedule attribute Phase attribute
default_settings.billing_thresholds phases.billing_thresholds
default_settings.collection_method phases.collection_method
default_settings.default_payment_method phases.default_payment_method
default_settings.invoice_settings phases.invoice_settings

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

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

curl https://api.stripe.com/v1/subscription_schedules \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer=cus_GBHHxuvBvO26Ea \
  -d start_date=now \
  -d end_behavior=release \
  -d phases[0][items][0][price]=price_1GqNdGAJVYItwOKqEHb \
  -d phases[0][items][0][quantity]=1 \
  -d phases[0][iterations]=12

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::SubscriptionSchedule.create({
  customer: 'cus_GBXUtjZo0nHBmW',
  start_date: 'now',
  end_behavior: 'release',
  phases: [
    {
      items: [
        {price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 1},
      ],
      iterations: 12,
    },
  ],
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.SubscriptionSchedule.create(
  customer='cus_GBXV9Q95NFT80k',
  start_date='now',
  end_behavior="release",
  phases=[
    {
      'items': [
        {'price': 'price_1GqNdGAJVYItwOKqEHb', 'quantity': 1},
      ],
      'iterations': 12,
    },
  ],
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\SubscriptionSchedule::create([
  'customer' => 'cus_GBXVvM3Lyqlb92',
  'start_date' => 'now',
  'end_behavior' => 'release',
  'phases' => [
    [
      'items' => [
        [
          'price' => 'price_1GqNdGAJVYItwOKqEHb',
          'quantity' => 1,
        ],
      ],
      'iterations' => 12,
    ],
  ],
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionScheduleCreateParams params =
  SubscriptionScheduleCreateParams.builder()
    .setCustomer("cus_GBXVzJZPdLuVU7")
    .setStartDate(SubscriptionScheduleCreateParams.StartDate.NOW)
    .setEndBehavior(SubscriptionScheduleCreateParams.EndBehavior.RELEASE)
    .addPhase(
      SubscriptionScheduleCreateParams.Phase.builder()
        .addItem(
          SubscriptionScheduleCreateParams.Phase.Item.builder()
            .setPrice("price_1GqNdGAJVYItwOKqEHb")
            .setQuantity(1L)
            .build())
        .setIterations(12L)
        .build())
    .build();

SubscriptionSchedule schedule = SubscriptionSchedule.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const schedule = await stripe.subscriptionSchedules.create({
  customer: 'cus_G8BQyXLV4wIrlu',
  start_date: 'now',
  end_behavior: 'release',
  phases: [
    {
      items: [{ price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 1 }],
      iterations: 12,
    },
  ],
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionScheduleParams{
  Customer: stripe.String("cus_G8BQyXLV4wIrlu"),
  StartDateNow: stripe.Bool(true),
  EndBehavior: stripe.String(string(stripe.SubscriptionScheduleEndBehaviorRelease)),
  Phases: []*stripe.SubscriptionSchedulePhaseParams{
    {
      Items: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Price: stripe.String("price_1GqNdGAJVYItwOKqEHb"),
          Quantity: stripe.Int64(1),
        },
      },
      Iterations: stripe.Int64(12),
    },
  },
}
schedule, _ := subschedule.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionScheduleCreateOptions
{
  Customer = "cus_GBZpSoDXILjq1a",
  StartDate = SubscriptionScheduleStartDate.Now,
  EndBehavior = "release",
  Phases = new List<SubscriptionSchedulePhaseOptions>
  {
    new SubscriptionSchedulePhaseOptions
    {
      Items = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Price = "price_1GqNdGAJVYItwOKqEHb",
          Quantity = 1,
        },
      },
      Iterations = 12,
    },
  },
};
var service = new SubscriptionScheduleService();
var schedule = service.Create(options);

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:

curl https://api.stripe.com/v1/subscription_schedules \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d from_subscription=sub_GB98WOvaRAWPl6

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::SubscriptionSchedule.create({
  from_subscription: 'sub_GB98WOvaRAWPl6',
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.SubscriptionSchedule.create(
  from_subscription='sub_GB98WOvaRAWPl6',
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\SubscriptionSchedule::create([
  'from_subscription' => 'sub_GB98WOvaRAWPl6',
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionScheduleCreateParams params =
  SubscriptionScheduleCreateParams.builder()
    .setFromSubscription("sub_GB98WOvaRAWPl6")
    .build();

SubscriptionSchedule schedule = SubscriptionSchedule.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const schedule = await stripe.subscriptionSchedules.create({
  from_subscription: 'sub_GB98WOvaRAWPl6'
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionScheduleParams{
  FromSubscription: stripe.String("sub_GB98WOvaRAWPl6"),
}
schedule, _ := subschedule.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionScheduleCreateOptions
{
  FromSubscription = "cus_GBGtWriHqoHUxj",
};
var service = new SubscriptionScheduleService();
var schedule = service.Create(options);

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.

Updating subscription schedules

You can only update the current and future phases on subscription schedules. When updating a subscription schedule, you need to pass in all current and future phases that you want to keep. You still receive information in the response about past 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:

curl https://api.stripe.com/v1/subscription_schedules/sub_sched_1FSRtAILNmKrzH4z9scwDpeL \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d phases[0][items][0][price]=price_1GqNdGAJVYItwOKqEHb \
  -d phases[0][items][0][quantity]=2 \
  -d phases[0][start_date]=1577865600 \
  -d phases[0][end_date]=1580544000

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::SubscriptionSchedule.update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  {
    phases: [
      {
        items: [
          {price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 2},
        ],
        start_date: 1577865600,
        end_date: 1580544000,
      },
    ],
  },
)

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.SubscriptionSchedule.modify(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  phases=[
    {
      'items': [
        {'price': 'price_1GqNdGAJVYItwOKqEHb', 'quantity': 2},
      ],
      'start_date': 1577865600,
      'end_date': 1580544000,
    },
  ],
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\SubscriptionSchedule::update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  [
    'phases' => [
      [
        'items' => [
          [
            'price' => 'price_1GqNdGAJVYItwOKqEHb',
            'quantity' => 2,
          ],
        ],
        'start_date' => 1577865600,
        'end_date' => 1580544000,
      ],
    ],
  ]
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionSchedule subscriptionSchedule =
  SubscriptionSchedule.retrieve(
    "sub_sched_1FSRtAILNmKrzH4z9scwDpeL"
  );

SubscriptionScheduleUpdateParams params =
  SubscriptionScheduleUpdateParams.builder()
    .addPhase(
      SubscriptionScheduleUpdateParams.Phase.builder()
        .addItem(
          SubscriptionScheduleUpdateParams.Phase.Item.builder()
            .setPrice("price_1GqNdGAJVYItwOKqEHb")
            .setQuantity(2L)
            .build())
        .setStartDate(1577865600L)
        .setEndDate(1580544000L)
        .build())
    .build();

SubscriptionSchedule subscriptionSchedule =
  subscriptionSchedule.update(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const schedule = await stripe.subscriptionSchedules.update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  {
    phases: [
      {
        items: [{ price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 2 }],
        start_date: 1577865600,
        end_date: 1580544000,
      },
    ],
  },
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionScheduleParams{
  Phases: []*stripe.SubscriptionSchedulePhaseParams{
    {
      Items: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Price: stripe.String("price_1GqNdGAJVYItwOKqEHb"),
          Quantity: stripe.Int64(2),
        },
      },
      StartDate: stripe.Int64(1577865600),
      EndDate: stripe.Int64(1580544000),
    },
  },
}
schedule, _ := subschedule.Update(
  "sub_sched_1FSRtAILNmKrzH4z9scwDpeL",
  params,
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionScheduleUpdateOptions
{
  Phases = new List<SubscriptionSchedulePhaseOptions>
  {
    new SubscriptionSchedulePhaseOptions
    {
      Items = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Price = "price_1GqNdGAJVYItwOKqEHb",
          Quantity = 2,
        },
      },
      StartDate = 1577865600,
      EndDate = 1580544000,
    },
  },
};
var service = new SubscriptionScheduleService();
service.Update(
  "sub_sched_1FSRtAILNmKrzH4z9scwDpeL",
  options
);

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:

curl https://api.stripe.com/v1/subscription_schedules/sub_sched_1FSRtAILNmKrzH4z9scwDpeL \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d phases[0][items][0][price]=price_1GqNdGAJVYItwOKqEHb \
  -d phases[0][items][0][quantity]=1 \
  -d phases[0][start_date]=1577865600 \
  -d phases[0][end_date]=now \
  -d phases[1][items][0][price]=price_1GqNdGAJVYItwOKqEHb \
  -d phases[1][items][0][quantity]=2 \
  -d phases[1][start_date]=now \
  -d phases[1][end_date]=1580544000

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::SubscriptionSchedule.update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  {
    phases: [
      {
        items: [
          {price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 1},
        ],
        start_date: 1577865600,
        end_date: 'now',
      },
      {
        items: [
          {price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 2},
        ],
        start_date: 'now',
        end_date: 1580544000,
      },
    ],
  },
)

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.SubscriptionSchedule.modify(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  phases=[
    {
      'items': [
        {'price': 'price_1GqNdGAJVYItwOKqEHb', 'quantity': 1},
      ],
      'start_date': 1577865600,
      'end_date': 'now',
    },
    {
      'items': [
        {'price': 'price_1GqNdGAJVYItwOKqEHb', 'quantity': 2},
      ],
      'start_date': 'now',
      'end_date': 1580544000,
    },
  ],
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\SubscriptionSchedule::update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL', [
  'phases' => [
    [
      'items' => [
        [
          'price' => 'price_1GqNdGAJVYItwOKqEHb',
          'quantity' => 1,
        ],
      ],
      'start_date' => 1577865600,
      'end_date' => 'now',
    ],
    [
      'items' => [
        [
          'price' => 'price_1GqNdGAJVYItwOKqEHb',
          'quantity' => 2,
        ],
      ],
      'start_date' => 'now',
      'end_date' => 1580544000,
    ],
  ],
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionSchedule subscriptionSchedule =
  SubscriptionSchedule.retrieve(
    "sub_sched_1FSRtAILNmKrzH4z9scwDpeL"
  );

SubscriptionScheduleUpdateParams params =
  SubscriptionScheduleUpdateParams.builder()
    .addPhase(
      SubscriptionScheduleUpdateParams.Phase.builder()
        .addItem(
          SubscriptionScheduleUpdateParams.Phase.Item.builder()
            .setPrice("price_1GqNdGAJVYItwOKqEHb")
            .setQuantity(1L)
            .build())
        .setStartDate(1577865600L)
        .setEndDate("now")
        .build())
    .addPhase(
      SubscriptionScheduleUpdateParams.Phase.builder()
        .addItem(
          SubscriptionScheduleUpdateParams.Phase.Item.builder()
            .setPrice("price_1GqNdGAJVYItwOKqEHb")
            .setQuantity(2L)
            .build())
        .setStartDate("now")
        .setEndDate(1580544000L)
        .build())
    .build();

SubscriptionSchedule subscriptionSchedule =
  subscriptionSchedule.update(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const schedule = await stripe.subscriptionSchedules.update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  {
    phases: [
      {
        items: [{ price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 1 }],
        start_date: 1577865600,
        end_date: 'now',
      },
      {
        items: [{ price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 2 }],
        start_date: 'now',
        end_date: 1580544000,
      },
    ],
  },
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionScheduleParams{
  Phases: []*stripe.SubscriptionSchedulePhaseParams{
    {
      Items: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Price: stripe.String("price_1GqNdGAJVYItwOKqEHb"),
          Quantity: stripe.Int64(1),
        },
      },
      StartDate: stripe.Int64(1577865600),
      EndDate: stripe.String("now"),
    },
    {
      Items: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Price: stripe.String("price_1GqNdGAJVYItwOKqEHb"),
          Quantity: stripe.Int64(2),
        },
      },
      StartDate: stripe.String("now"),
      EndDate: stripe.Int64(1580544000),
    },
  },
}
schedule, _ := subschedule.Update(
  "sub_sched_1FSRtAILNmKrzH4z9scwDpeL",
  params,
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionScheduleUpdateOptions
{
  Phases = new List<SubscriptionSchedulePhaseOptions>
  {
    new SubscriptionSchedulePhaseOptions
    {
      Items = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Price = "price_1GqNdGAJVYItwOKqEHb",
          Quantity = 1,
        },
      },
      StartDate = 1577865600,
      EndDate = "now",
    },
    new SubscriptionSchedulePhaseOptions
    {
      Items = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Price = "price_1GqNdGAJVYItwOKqEHb",
          Quantity = 2,
        },
      },
      StartDate = "now",
      EndDate = 1580544000,
    },
  },
};
var service = new SubscriptionScheduleService();
service.Update(
  "sub_sched_1FSRtAILNmKrzH4z9scwDpeL",
  options
);

To add additional phases to a subscription schedule, pass in the current phase, and then define your new phases:

curl https://api.stripe.com/v1/subscription_schedules/sub_sched_1FSRtAILNmKrzH4z9scwDpeL \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d phases[0][items][0][price]=price_1GqNdGAJVYItwOKqEHb \
  -d phases[0][items][0][quantity]=1 \
  -d phases[0][start_date]=1577865600 \
  -d phases[0][end_date]=1580544000 \
  -d phases[1][items][0][price]=price_1GqNdGAJVYItwOKqEHb \
  -d phases[1][items][0][quantity]=2 \
  -d phases[1][iterations]=1

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::SubscriptionSchedule.update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  {
    phases: [
      {
        items: [
          {price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 1},
        ],
        start_date: 1577865600,
        end_date: 1580544000,
      },
      {
        items: [
          {price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 2},
        ],
        iterations: 1,
      },
    ],
  },
)

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.SubscriptionSchedule.modify(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  phases=[
    {
      'items': [
        {'price': 'price_1GqNdGAJVYItwOKqEHb', 'quantity': 1},
      ],
      'start_date': 1577865600,
      'end_date': 1580544000,
    },
    {
      'items': [
        {'price': 'price_1GqNdGAJVYItwOKqEHb', 'quantity': 2},
      ],
      'iterations': 1,
    },
  ],
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\SubscriptionSchedule::update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  [
    'phases' => [
      [
        'items' => [
          [
            'price' => 'price_1GqNdGAJVYItwOKqEHb',
            'quantity' => 1,
          ],
        ],
        'start_date' => 1577865600,
        'end_date' => 1580544000,
      ],
      [
        'items' => [
          [
            'price' => 'price_1GqNdGAJVYItwOKqEHb',
            'quantity' => 2,
          ],
        ],
        'iterations' => 1,
      ],
    ],
  ]
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionSchedule subscriptionSchedule =
  SubscriptionSchedule.retrieve(
    "sub_sched_1FSRtAILNmKrzH4z9scwDpeL"
  );

SubscriptionScheduleUpdateParams params =
  SubscriptionScheduleUpdateParams.builder()
    .addPhase(
      SubscriptionScheduleUpdateParams.Phase.builder()
        .addItem(
          SubscriptionScheduleUpdateParams.Phase.Item.builder()
            .setPrice("price_1GqNdGAJVYItwOKqEHb")
            .setQuantity(1L)
            .build())
        .setStartDate(1577865600L)
        .setEndDate(1580544000L)
        .build())
    .addPhase(
      SubscriptionScheduleUpdateParams.Phase.builder()
        .addItem(
          SubscriptionScheduleUpdateParams.Phase.Item.builder()
            .setPrice("price_1GqNdGAJVYItwOKqEHb")
            .setQuantity(2L)
            .build())
        .setIterations(1L)
        .build())
    .build();

SubscriptionSchedule subscriptionSchedule =
  subscriptionSchedule.update(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const schedule = await stripe.subscriptionSchedules.update(
  'sub_sched_1FSRtAILNmKrzH4z9scwDpeL',
  {
    phases: [
      {
        items: [{ price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 1 }],
        start_date: 1577865600,
        end_date: 1580544000,
      },
      {
        items: [{ price: 'price_1GqNdGAJVYItwOKqEHb', quantity: 2 }],
        iterations: 1,
      },
    ],
  },
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionScheduleParams{
  Phases: []*stripe.SubscriptionSchedulePhaseParams{
    {
      Items: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Price: stripe.String("price_1GqNdGAJVYItwOKqEHb"),
          Quantity: stripe.Int64(1),
        },
      },
      StartDate: stripe.Int64(1577865600),
      EndDate: stripe.Int64(1580544000),
    },
    {
      Items: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Price: stripe.String("price_1GqNdGAJVYItwOKqEHb"),
          Quantity: stripe.Int64(2),
        },
      },
      Iterations: stripe.Int64(1),
    },
  },
}
schedule, _ := subschedule.Update(
  "sub_sched_1FSRtAILNmKrzH4z9scwDpeL",
  params,
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionScheduleUpdateOptions
{
  Phases = new List<SubscriptionSchedulePhaseOptions>
  {
    new SubscriptionSchedulePhaseOptions
    {
      Items = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Price = "price_1GqNdGAJVYItwOKqEHb",
          Quantity = 1,
        },
      },
      StartDate = 1577865600,
      EndDate = 1580544000,
    },
    new SubscriptionSchedulePhaseOptions
    {
      Items = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Price = "price_1GqNdGAJVYItwOKqEHb",
          Quantity = 2,
        },
      },
      Iterations = 1,
    },
  },
};
var service = new SubscriptionScheduleService();
service.Update(
  "sub_sched_1FSRtAILNmKrzH4z9scwDpeL",
  options
);

Next steps

Now that you understand how subscription schedules work, you can learn more about the use cases.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Phases
Creating subscription schedules
Updating subscription schedules
Next steps