Schedules

Schedules

• A schedule moves a customer between plans over dated phases. Create with createSchedule, preview with previewCreateSchedule.
• A customer holds ONE schedule. Calling createSchedule again replaces all of it — the old phases and their scheduled plans are deleted. There is no update or delete endpoint.
• To change a schedule, resend the full phase list, including phases that already started. To drop future phases, resend with only the immediate phase.
• Plans the schedule never placed (e.g. a separately attached add-on) are always kept.

Phase timing

• Every phase needs exactly one of starts_at (epoch ms, or "now") or starting_after ({ duration_type: "month" | "year", duration_count }).
• starts_at: "now" is first-phase only; starting_after is never allowed on the first phase.
• The first phase must start now. A future first starts_at is rejected. A past one works only for paid recurring plans on a customer with no existing Stripe subscription.
• starts_at values must be strictly increasing.
• Quirk: unless you pass billing_cycle_anchor, a later phase starting within 12 hours of the current billing cycle boundary is silently snapped onto that boundary.

Plans in a phase