Checkout Sessions
NEWPayments
Subscriptions
Discounts
Licenses
Customers
Customer Wallets
NEWProducts
Usage Events
Payouts
Webhooks
Miscellaneous
Subscriptions
Preview Plan Change
Preview the effects of a subscription plan change before committing to it. Returns the immediate charge amount and the new subscription details without making any actual changes.
POST
/
subscriptions
/
{subscription_id}
/
change-plan
/
preview
JavaScript
Copy
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});
const response = await client.subscriptions.previewChangePlan('subscription_id', {
product_id: 'product_id',
proration_billing_mode: 'prorated_immediately',
quantity: 0,
});
console.log(response.immediate_charge);Copy
{
"immediate_charge": {
"line_items": [
{
"currency": "AED",
"id": "<string>",
"product_id": "<string>",
"proration_factor": 123,
"quantity": 123,
"tax_inclusive": true,
"type": "subscription",
"unit_price": 123,
"description": "<string>",
"name": "<string>",
"tax": 123,
"tax_rate": 123
}
],
"summary": {
"currency": "AED",
"customer_credits": 123,
"settlement_amount": 123,
"settlement_currency": "AED",
"total_amount": 123,
"settlement_tax": 123,
"tax": 123
}
},
"new_plan": {
"addons": [
{
"addon_id": "<string>",
"quantity": 123
}
],
"billing": {
"country": "AF",
"city": "<string>",
"state": "<string>",
"street": "<string>",
"zipcode": "<string>"
},
"cancel_at_next_billing_date": true,
"created_at": "2023-11-07T05:31:56Z",
"currency": "AED",
"customer": {
"customer_id": "<string>",
"email": "<string>",
"name": "<string>",
"metadata": {},
"phone_number": "<string>"
},
"metadata": {},
"meters": [
{
"currency": "AED",
"free_threshold": 123,
"measurement_unit": "<string>",
"meter_id": "<string>",
"name": "<string>",
"price_per_unit": "10.50",
"description": "<string>"
}
],
"next_billing_date": "2023-11-07T05:31:56Z",
"on_demand": true,
"payment_frequency_count": 123,
"payment_frequency_interval": "Day",
"previous_billing_date": "2023-11-07T05:31:56Z",
"product_id": "<string>",
"quantity": 123,
"recurring_pre_tax_amount": 123,
"status": "pending",
"subscription_id": "<string>",
"subscription_period_count": 123,
"subscription_period_interval": "Day",
"tax_inclusive": true,
"trial_period_days": 123,
"cancelled_at": "2023-11-07T05:31:56Z",
"discount_cycles_remaining": 123,
"discount_id": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"payment_method_id": "<string>",
"tax_id": "<string>"
}
}Use this endpoint to show customers exactly what they’ll be charged when upgrading or downgrading their subscription, improving transparency and reducing support requests.
Use Cases
- Checkout confirmation: Display the prorated charge before customers confirm a plan change
- Pricing calculators: Build upgrade/downgrade calculators in your application
- Customer self-service: Let customers explore plan options with accurate pricing
Response Fields
The preview response includes:| Field | Description |
|---|---|
immediate_charge | The charge that would be created immediately, including line items and summary |
new_plan | The full subscription object showing how it would look after the plan change |
The
immediate_charge.summary contains the total amount that would be charged. Use this to display pricing to your customers before they confirm the plan change.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Subscription Id
Body
application/json
Unique identifier of the product to subscribe to
Proration Billing Mode
Available options:
prorated_immediately, full_immediately, difference_immediately Number of units to subscribe for. Must be at least 1.
Required range:
x >= 0Response
Preview of subscription plan change
Show child attributes
Show child attributes
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Available options:
AED, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, JMD, JOD, JPY, KES, KGS, KHR, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SZL, THB, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW Available options:
subscription Show child attributes
Show child attributes
Available options:
AED, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, JMD, JOD, JPY, KES, KGS, KHR, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SZL, THB, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW Available options:
AED, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, JMD, JOD, JPY, KES, KGS, KHR, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SZL, THB, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW Response struct representing subscription details
Show child attributes
Show child attributes
Billing address details for payments
Show child attributes
Show child attributes
Two-letter ISO country code (ISO 3166-1 alpha-2)
Available options:
AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, US, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW City name
State or province name
Street address including house number and unit/apartment if applicable
Postal code or ZIP code
Indicates if the subscription will cancel at the next billing date
Timestamp when the subscription was created
Currency used for the subscription payments
Available options:
AED, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, JMD, JOD, JPY, KES, KGS, KHR, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SZL, THB, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW Customer details associated with the subscription
Show child attributes
Show child attributes
Unique identifier for the customer
Email address of the customer
Full name of the customer
Phone number of the customer
Meters associated with this subscription (for usage-based billing)
Show child attributes
Show child attributes
Available options:
AED, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, JMD, JOD, JPY, KES, KGS, KHR, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SZL, THB, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW Example:
"10.50"
Timestamp of the next scheduled billing. Indicates the end of current billing period
Wether the subscription is on-demand or not
Number of payment frequency intervals
Time interval for payment frequency (e.g. month, year)
Available options:
Day, Week, Month, Year Timestamp of the last payment. Indicates the start of current billing period
Identifier of the product associated with this subscription
Number of units/items included in the subscription
Amount charged before tax for each recurring payment in smallest currency unit (e.g. cents)
Current status of the subscription
Available options:
pending, active, on_hold, cancelled, failed, expired Unique identifier for the subscription
Number of subscription period intervals
Time interval for the subscription period (e.g. month, year)
Available options:
Day, Week, Month, Year Indicates if the recurring_pre_tax_amount is tax inclusive
Number of days in the trial period (0 if no trial)
Cancelled timestamp if the subscription is cancelled
Number of remaining discount cycles if discount is applied
The discount id if discount is applied
Timestamp when the subscription will expire
Saved payment method id used for recurring charges
Tax identifier provided for this subscription (if applicable)
Was this page helpful?
⌘I
JavaScript
Copy
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});
const response = await client.subscriptions.previewChangePlan('subscription_id', {
product_id: 'product_id',
proration_billing_mode: 'prorated_immediately',
quantity: 0,
});
console.log(response.immediate_charge);Copy
{
"immediate_charge": {
"line_items": [
{
"currency": "AED",
"id": "<string>",
"product_id": "<string>",
"proration_factor": 123,
"quantity": 123,
"tax_inclusive": true,
"type": "subscription",
"unit_price": 123,
"description": "<string>",
"name": "<string>",
"tax": 123,
"tax_rate": 123
}
],
"summary": {
"currency": "AED",
"customer_credits": 123,
"settlement_amount": 123,
"settlement_currency": "AED",
"total_amount": 123,
"settlement_tax": 123,
"tax": 123
}
},
"new_plan": {
"addons": [
{
"addon_id": "<string>",
"quantity": 123
}
],
"billing": {
"country": "AF",
"city": "<string>",
"state": "<string>",
"street": "<string>",
"zipcode": "<string>"
},
"cancel_at_next_billing_date": true,
"created_at": "2023-11-07T05:31:56Z",
"currency": "AED",
"customer": {
"customer_id": "<string>",
"email": "<string>",
"name": "<string>",
"metadata": {},
"phone_number": "<string>"
},
"metadata": {},
"meters": [
{
"currency": "AED",
"free_threshold": 123,
"measurement_unit": "<string>",
"meter_id": "<string>",
"name": "<string>",
"price_per_unit": "10.50",
"description": "<string>"
}
],
"next_billing_date": "2023-11-07T05:31:56Z",
"on_demand": true,
"payment_frequency_count": 123,
"payment_frequency_interval": "Day",
"previous_billing_date": "2023-11-07T05:31:56Z",
"product_id": "<string>",
"quantity": 123,
"recurring_pre_tax_amount": 123,
"status": "pending",
"subscription_id": "<string>",
"subscription_period_count": 123,
"subscription_period_interval": "Day",
"tax_inclusive": true,
"trial_period_days": 123,
"cancelled_at": "2023-11-07T05:31:56Z",
"discount_cycles_remaining": 123,
"discount_id": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"payment_method_id": "<string>",
"tax_id": "<string>"
}
}