---
title: "Preview a subscription change"
method: POST
path: "/api/v1/billing/subscription/preview"
tags: ["billing"]
---

# Preview a subscription change

`POST /api/v1/billing/subscription/preview`

Computes the prorated amount that a subscription change would invoice **today**, without making any change or charge. Use it to show the customer what they'll pay before confirming an interval switch, a number addition, or a coupon application. The amounts come straight from Stripe's invoice preview — the same engine that bills the actual change.

Provide the target state: `interval` and/or `quantity` (each defaults to the subscription's current value when omitted), and an optional `promotionCode`. An invalid, expired, or inapplicable code is rejected with `400`. Requires an active subscription.

## Headers

- `Authorization` string, required

## Request body

- object
  - `interval` 'monthly' | 'annual' — Target billing interval. Defaults to the current interval.
  - `quantity` integer — Target number count (one unit per phone number). Defaults to the current quantity.
  - `promotionCode` string — Optional customer-facing promotion code; the preview reflects the discount it produces.

## Response `200`

The previewed charge for the proposed change.

- BillingPreviewSubscriptionChangeResponse200
  - `amountDueCents` integer — Amount that would be charged today, in USD cents (prorations and discounts included).
  - `currency` string
  - `prorationDate` integer — Unix timestamp (seconds) the proration was calculated as of. Pass it back as `prorationDate` to the change endpoint to charge exactly this quoted amount.
  - `discountCents` integer — Total discount applied by the coupon, in USD cents (0 when no coupon or no effect).
  - `lines` ApiV1BillingSubscriptionPreviewPostResponsesContentApplicationJsonSchemaLinesItems[] — The invoice preview line items (proration credits appear as negatives).
    - `description` string
    - `amountCents` integer

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