Subscription Schedule

A subscription schedule is the Stripe object that plans future changes to a subscription. You describe the sequence once, such as three months at 50% off and then full price, and Stripe applies each change on its date. Nobody has to remember to edit the customer's plan in March.

How Stripe subscription schedules work

A SubscriptionSchedule is made of phases. Each phase sets the prices, quantities, coupons, and other settings that apply while it runs, and how long it lasts. Phases run in order and only one is active at a time. The end of one phase is the start of the next. You can define up to 10 current or future phases at once, and past phases don't count toward the limit.

When a phase starts, Stripe copies its settings onto the subscription. The subscription itself changes, so customer.subscription.updated fires as it would for a manual edit. Each phase also sets how proration works when it begins, because a mid-cycle quantity increase can create an extra charge or a credit.

You can create schedules in the Billing Dashboard's subscription editor or with the API. A schedule can start a new subscription, including one that begins on a future date or is backdated. With the API you can attach a schedule to an existing subscription by passing from_subscription.

How a schedule ends

The end_behavior field decides what happens after the last phase.

• release is the default. The schedule ends and the subscription keeps billing on the last phase's settings.
• cancel ends the schedule and cancels the subscription too. Installment plans use it, for example six monthly payments and then stop.

You can also act on a schedule while it runs. Releasing a schedule removes it and its remaining phases and leaves the subscription billing as before. Canceling a schedule cancels its subscription as well. Both only work while the schedule's status is not_started or active.

Subscription schedule events

A schedule's status moves from not_started to active, then ends as completed, released, or canceled. Stripe sends these events:

• subscription_schedule.created and subscription_schedule.updated.
• subscription_schedule.expiring, seven days before a schedule expires.
• subscription_schedule.completed, subscription_schedule.released, and subscription_schedule.canceled.
• subscription_schedule.aborted, when the schedule is canceled because its subscription was canceled for non-payment.

Stripe can also create a schedule for you, for example when a customer schedules a downgrade in the Customer Portal. Store the ID from subscription_schedule.created so later API updates go through the schedule.

Common uses

• Introductory offers. A discounted first phase, then the standard price.
• Contract step-ups. A negotiated price increase after year one.
• Seat ramps. Quantity rising from 10 seats to 25 and then 50 on agreed dates.
• Future starts. A subscription that begins on the date a signed contract does.
• Scheduled downgrades. A cheaper plan that starts when the current billing period ends.

Why schedules need watching

A schedule changes billing with nobody looking. When an intro price ends, the next invoice jumps, and that's when customers question the bill, hit a decline on a card with a low limit, or cancel. A seat ramp the account team forgot produces a surprised customer. end_behavior: cancel on the wrong schedule ends a paying subscription.

Editing a schedule has its own traps. You can only change the current and future phases, and every update must include all of them. Stripe unsets any parameter you leave out, such as a discount or metadata. If a subscription has a schedule, change it through the Subscription Schedules API, or the next phase can overwrite your direct edit.

Schedules also make MRR movements predictable. A contracted step-up is expansion you can forecast months ahead.

What to do around a phase change

1. Before the change, success or sales use subscription_schedule.expiring or a calendar to warn customers whose price is about to rise. A short "your intro rate ends next month" email prevents angry cancellations and disputes.
2. At the change, finance confirms the first invoice at the new price was paid, not only created.
3. If that payment fails, finance and support treat it as a priority. A failure right after a price increase usually needs a conversation.
4. When editing, engineering passes every current and future phase and tests the change in a sandbox first.
5. Every quarter, the founder or finance checks that schedules meant to keep billing use release.

Subscription schedules and ChargeBell

ChargeBell has no alert for schedule events. It covers the moments where a schedule turns into a real result. Plan upgrades and downgrades have their own alert. If the first charge at a higher price fails, the payment failed alert is marked critical and comes through during quiet hours, and a later successful retry posts a payment recovered alert. If a schedule ends by canceling the subscription, the subscription canceled alert posts it with the MRR you lost.

A sensible routing sends plan changes to #customer-success, failed payments to #billing, and cancellations to #founders. See how to monitor Stripe subscriptions in Slack for a full setup.