v4

OpenAPI 3.1.02026-08-0255174167.5 KB

billing

Preview a subscription change

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.

post/api/v1/billing/subscription/preview

Headers

Authorizationstring required

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

Request body

interval'monthly' | 'annual'

Target billing interval. Defaults to the current interval.

quantityinteger

Target number count (one unit per phone number). Defaults to the current quantity.

promotionCodestring

Optional customer-facing promotion code; the preview reflects the discount it produces.

Response

The previewed charge for the proposed change.

amountDueCentsinteger

Amount that would be charged today, in USD cents (prorations and discounts included).

currencystring

prorationDateinteger

Unix timestamp (seconds) the proration was calculated as of. Pass it back as prorationDate to the change endpoint to charge exactly this quoted amount.

discountCentsinteger

Total discount applied by the coupon, in USD cents (0 when no coupon or no effect).