Preview a subscription change | Dial — Communication Stack for AI Agents

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.

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.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

intervalenumOptional

Target billing interval. Defaults to the current interval.

Allowed values:

quantityintegerOptional>=1

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

promotionCodestringOptional

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

lineslist of objects

The invoice preview line items (proration credits appear as negatives).

Errors

400

Bad Request Error

401

Unauthorized Error

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

1	{
2	"amountDueCents": 1500,
3	"currency": "usd",
4	"prorationDate": 1718000000,
5	"discountCents": 300,
6	"lines": [
7	{
8	"description": "Remaining time on 3 × Dial Subscription",
9	"amountCents": 1800
10	}
11	]
12	}