Create a subscription schedule with POST /v1/subscription_schedules, setting start_date and phases array; each phase requires items (price IDs and quantities), iterations or end_date, and proration_behavior
Set the first phase with a trial_end or a free price to model a trial period, then the second phase with the paid price
Add a third phase with a discounted coupon by including coupon on the phase object to apply a time-limited discount automatically
Set end_behavior=release on the schedule so the subscription continues after all phases end without expiring
Monitor schedule transitions by listening for customer.subscription.updated webhook events; the subscription object's schedule field will reference the active schedule ID
Cancel or modify the schedule mid-cycle with POST /v1/subscription_schedules/SCHEDULE_ID with phases updates; use proration_behavior=always_invoice to immediately generate proration invoices
Known gotchas
Phases are processed sequentially and cannot overlap; if end_date of one phase does not align with start_date of the next, Stripe will return a validation error
Proration behavior on a phase controls prorations at the phase transition, not within the phase — changing a price within a phase still uses the subscription-level proration_behavior
subscription_schedules cannot be applied to subscriptions that already have a schedule; you must release the existing schedule before attaching a new one
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp