Change the subscription billing interval | Dial — Communication Stack for AI Agents

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

AuthorizationBearer

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

Request

This endpoint expects an object.

intervalenumRequired

Allowed values:

promotionCodestringOptional

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

prorationDateintegerOptional

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.

intervalenum

Errors

400

Bad Request Error

401

Unauthorized Error

$	curl -X POST https://getdial.ai/api/v1/billing/subscription/change \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"interval": "annual"
>	}'