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