Create or retrieve a Customer object and attach a default payment method
Create a SubscriptionSchedule via POST /v1/subscription_schedules with start_behavior set to now and phases array containing the promotional phase (price, iterations, coupon) followed by the standard phase (price, no end_date so it runs indefinitely)
Set proration_behavior on each phase transition to create_prorations or none based on billing policy
Listen for customer.subscription.updated webhooks to detect phase transitions and update your application state
To modify the schedule later, use POST /v1/subscription_schedules/:id with the updated phases array; the end_behavior field controls what happens when all phases complete
Known gotchas
If you omit end_behavior and all phases have a defined end, the subscription is cancelled automatically when the last phase expires; set end_behavior to release to convert it to an unscheduled subscription instead
Phases must be provided in chronological order with no gaps; if the second phase start_date does not immediately follow the first phase end, the API returns an error
Coupon and discount objects attached at the phase level override customer-level discounts; ensure discount stacking logic is intentional
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