Get Subscription Proration Details

Use this endpoint to calculate exactly what you will be charged when switching between plans or adding add-ons mid-billing-cycle. The proration amount is based on the remaining time on your current subscription and the cost of the new one. Provide your subscription ID as a path parameter, along with the plan_product_id and optionally add_ons as query parameters.

Call this endpoint before confirming a subscription change — use the returned difference.total to see the exact amount you will be charged today, including tax, before you confirm.

Common use cases:

Plan upgrade preview — See exactly what you will be charged today when upgrading from Starter to Basic mid-cycle, including the unused credit from your current subscription offset against the new subscription cost.
Add-on cost estimation — Calculate how much adding SMS credits or extra seats will cost for the remainder of your current billing period before you confirm the purchase.
Tax-inclusive pricing display — Use difference.tax.percent and difference.tax.amount to see a fully itemized breakdown including your applicable tax rate, which varies by your billing region.
Yearly vs monthly comparison — Call this endpoint twice with different plan_product_id values (monthly vs yearly variant) to compare costs side by side before you commit.
Downgrade credit display — When switching to a lower subscription, data.plans.current.amount will be negative — this is a credit you receive for unused time on your current plan.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, you receive a full proration breakdown: your current plan credit, new plan charge, any add-on charges, and the net total with tax.
add_ons will be null if you did not include add-ons in your request.
If your request fails, an appropriate error message will be returned.

Path Parameters

id string
Your subscription ID. Retrieve it from the Get All Subscriptions endpoint — look for subscription_id where active: true.

Query Parameters

plan_product_id string
The Stripe price ID of the plan you want to switch to. Pass the monthly variant to calculate monthly proration, or the yearly variant to calculate annual proration. You can retrieve available price IDs from your plan listing endpoint.
add_ons string (URL-encoded JSON array)

ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).