Stripe subscription schedules: multi-phase subscriptions without the mess

TL;DR

Set it deliberately; the default may not be what the sales conversation promised. - Listen for subscription\_schedule.completed and the phase-transition events. Any subscription that changes on a date, trial to paid, promo price to standard, annual step-up, is a multi-phase subscription. Agents implement these with cron jobs that update the subscription on the day, which fails when the job fails.

When to use

You are seeing this: Subscription schedules declare the phases up front and Stripe executes the transitions. Use this skill when you run into "Stripe subscription schedules: multi-phase subscriptions without the mess".

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe subscription schedules for multi-phase billing

Any subscription that changes on a date, trial to paid, promo price to standard, annual step-up, is a multi-phase subscription. Agents implement these with cron jobs that update the subscription on the day, which fails when the job fails. Subscription schedules declare the phases up front and Stripe executes the transitions.

The model

1. A schedule has phases. Each phase has its own items, prices, trial settings, and an end date (or iteration count).
2. Create the schedule from an existing subscription or fresh. Phase one might be a 14-day trial; phase two the standard monthly price; phase three an annual plan.
3. At each phase boundary Stripe transitions automatically: the subscription updates, proration is handled per your settings, and webhooks fire.

What to watch

• The trial property on schedule phases (added in a recent API version) controls trial behavior per phase. Set it deliberately; the default may not be what the sales conversation promised.
• Listen for subscription_schedule.completed and the phase-transition events. Your app's entitlements must follow the schedule, not a local copy of "what phase we think we are in."
• Schedules and the Trial Offer API do not mix in the Dashboard during preview; manage trial-offer schedules via the API.

When not to use schedules

• Simple recurring billing with no planned changes: a plain subscription is enough.
• Changes driven by usage or user action rather than dates: handle those with subscription updates, not phases.
• One-off future changes with no pattern: a single scheduled update beats a whole schedule object.

The agent trap

Do not build a cron job that calls subscriptions.update on a date. That is a distributed-systems bug wearing a calendar costume: missed runs, double runs, and no audit trail. If the change is date-driven and known in advance, it belongs in a schedule.

Stripe's subscription schedule docs describe phases with per-phase items and trials, automatic transitions at phase boundaries, and the subscription_schedule.completed event. The changelog notes the trial property on schedule phases. Verified against live docs 2026-09-26.