---
title: "Change the subscription billing interval"
method: POST
path: "/api/v1/billing/subscription/change"
tags: ["billing"]
---

# Change the subscription billing interval

`POST /api/v1/billing/subscription/change`

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.

## Headers

- `Authorization` string, required

## Request body

- object
  - `interval` 'monthly' | 'annual', required
  - `promotionCode` string — 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.
  - `prorationDate` integer — 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 `200`

Interval change applied (or already on the target interval).

- BillingChangeSubscriptionIntervalResponse200
  - `changed` boolean — False when already on the target interval.
  - `interval` 'monthly' | 'annual'

## Other responses

- `400` — The request body failed validation.
- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)