Change the subscription billing interval
Switches the subscription billing interval (e.g. upgrade monthly → annual). Prorated and invoiced immediately; the new-period entitlement lands when that invoice is paid. Clears any scheduled cancellation. No-op if already on the target interval. Not available during impersonation.
Authentication
Your Dial API key, sent as Authorization: Bearer sk_live_...
Request
Optional customer-facing promotion code (e.g. LAUNCH20) to apply to the subscription. Resolved to its Stripe promotion code and handed to Stripe, which validates it and applies the discount per the underlying coupon’s own scope and duration. An invalid, expired, or inapplicable code is rejected with 400. Preview the discounted amount first with Preview a subscription change.
Optional Unix timestamp (seconds) from a prior preview’s prorationDate. When supplied, the proration is calculated as of that instant so the charged amount matches the previewed quote exactly. Omit to prorate as of now.
Response
Interval change applied (or already on the target interval).