— No Results

    Subscription Schedules API

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

    Subscription schedules are the primary way for you 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. Subscription schedules have a phases attribute that you use to define the changes you want to make. Once a schedule has transitioned through all its phases, the schedule 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 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 of your premium plan for the first three months of a subscription, and then return your customer to a basic plan afterwards. In this scenario, you’d create a subscription schedule where the first phase is three months long and contains the premium plan and a 50% off coupon. In the second phase, the plan would be reverted to the basic plan 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

    Subscriptions are billed based on the plan’s interval. For example, a plan with a monthly interval is billed every month. Phases have an iterations attribute that you use to specify how long a phase should last. This value is multiplied by the plan’s interval to determine the length of the phase. So if a subscription schedule phase defines a plan with a monthly interval and you set iterations=2, the phase will last 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. These values can be set manually, but Stripe recommends using iterations instead. Manually setting the start and end dates is prone to errors and should only be used for advanced use cases.

    Transitioning to the next phase

    Subscription schedules automatically transition from one phase to the next based on the cancel at attribute. This doesn’t cancel the subscription, it’s just the timestamp that triggers the transition to the next phase. When a phase starts, Stripe updates the subscription based on the next phase’s attributes. You can optionally enable proration to credit the user for unused items or time on the plan.

    Using trials

    Trial periods can be added 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 just part of the phase a trial. When scheduling updates, you must specify the new trial_end on each phase.

    Completing a schedule

    A subscription schedule is completed after the last phase is finished. When this happens, the subscription is released from the schedule and it behaves the same as it did before the schedule was applied. If you want to cancel a subscription after the last phase of a schedule is complete, you can set end_behavior to cancel.

    Phase attribute inheritance

    When a phase becomes active, all the attributes set on the phase are set on the subscription. After the phase ends, attributes remain the same unless the next phase modifies them, or if there is no default setting on the schedule. There are some attributes that you can set 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 is used as the default for all phases. When the same property is defined on both the schedule and the phase, the phase attribute overrides the schedule’s 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

    Managing 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/ \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer=cus_GBHHxuvBvO26Ea \
  -d start_date=now \
  -d end_behavior=release \
  -d phases[0][plans][0][plan]=plan_1234 \
  -d phases[0][plans][0][quantity]=1 \
  -d phases[0][iterations]=12

    # Set your secret key: remember to change this 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: [
    {
      plans: [
        {plan: 'plan_1234', quantity: 1},
      ],
      iterations: 12,
    },
  ],
})

    # Set your secret key: remember to change this 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=[
    {
      'plans': [
        {'plan': 'plan_1234', 'quantity': 1},
      ],
      'iterations': 12,
    },
  ],
)

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

StripeSubscriptionSchedule::create([
  'customer' => 'cus_GBXVvM3Lyqlb92',
  'start_date' => 'now',
  'end_behavior' => 'release',
  'phases' => [
    [
      'plans' => [
        [
          'plan' => 'plan_1234',
          'quantity' => 1,
        ],
      ],
      'iterations' => 12,
    ],
  ],
]);

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

List<Object> phases = new ArrayList<>();
List<Object> plans = new ArrayList<>();
Map<String, Object> plan1 = new HashMap<>();
plan1.put("plan", "plan_1234");
plan1.put("quantity", 1);
plans.add(plan1);
Map<String, Object> phase1 = new HashMap<>();
phase1.put("plans", plans);
phase1.put("iterations", 12);
phases.add(phase1);
Map<String, Object> params = new HashMap<>();
params.put("customer", "cus_GBXVzJZPdLuVU7");
params.put("start_date", "now");
params.put("end_behavior", "release");
params.put("phases", phases);

SubscriptionSchedule subscriptionSchedule = SubscriptionSchedule.create(params);

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

stripe.subscriptionSchedules.create(
  {
    customer: 'cus_G8BQyXLV4wIrlu',
    start_date: 'now',
    end_behavior: 'release',
    phases: [
      {
        plans: [{ plan: 'plan_1234', quantity: 1 }],
        iterations: 12
      }
    ]
  },
  function(err, subscriptionSchedule) {
     // asynchronously called
  }
);

    // Set your secret key: remember to change this 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{
    {
      Plans: []*stripe.SubscriptionSchedulePhaseItemParams{
        {
          Plan: stripe.String("plan_1234"),
          Quantity: stripe.Int64(1),
        },
      },
      Iterations: stripe.Int64(12),
    },
  },
}
schedule, _ := subschedule.New(params)

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

var options = new SubscriptionScheduleCreateOptions
{
  Customer = "cus_GBZpSoDXILjq1a",
  StartDate = SubscriptionScheduleStartDate.Now,
  EndBehavior = "release",
  Phases = new List<SubscriptionSchedulePhaseOptions>
  {
    new SubscriptionSchedulePhaseOptions
    {
      Plans = new List<SubscriptionSchedulePhaseItemOptions>
      {
        new SubscriptionSchedulePhaseItemOptions
        {
          Plan = "plan_1234",
          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 plan_1234 plan.
    • 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 change this 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 change this 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 change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

StripeSubscriptionSchedule::create([
  'from_subscription' => 'sub_GB98WOvaRAWPl6',
]);

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

Map<String, String> params = new HashMap<>();
params.put("from_subscription", "sub_GB98WOvaRAWPl6");

SubscriptionSchedule subscriptionSchedule = SubscriptionSchedule.create(params);

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

stripe.subscriptionSchedules.create(
  {
    from_subscription: 'sub_GB98WOvaRAWPl6'
  },
  function(err, subscriptionSchedule) {
    // asynchronously called
  }
);

    // Set your secret key: remember to change this 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 change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('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 subcription schedule cancels the subscription as well. If you just want to remove a schedule from a subscription, use the release call.

    Next steps

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

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team.

    You can chat live with other developers in #stripe on freenode or subscribe to our YouTube channel.

    On this page