v4

OpenAPI 3.1.02026-08-0255174167.5 KB

billing

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.

post/api/v1/billing/subscription/change

Headers

Authorizationstring required

Your Dial API key, sent as Authorization: Bearer sk_live_...

Request body

interval'monthly' | 'annual' required

promotionCodestring

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.

prorationDateinteger

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

changedboolean

False when already on the target interval.

interval'monthly' | 'annual'