Change Plan

Modify an existing subscription’s plan, enabling both upgrades and downgrades to different pricing tiers.

Note: This will use the existing payment information of the customer to upgrade/downgrade the plan.

POST /subscriptions/{subscription_id}/change-plan

JavaScript

JavaScript

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

await client.subscriptions.changePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

Scheduled Plan Changes

Use the effective_at parameter to control when the plan change takes effect:

Value	Behavior
immediately	Apply the plan change right away. This is the default.
next_billing_date	Schedule the change for the next billing date. The customer retains access to their current plan until the billing period ends.

Scheduled plan changes are ideal for downgrades — customers keep their current plan benefits until the end of the billing period, then automatically switch to the new plan.

To cancel a scheduled plan change before it takes effect, use the Cancel Scheduled Plan Change endpoint.

Payment Failure Handling

Use the on_payment_failure parameter to control what happens when the plan change payment fails:

Value	Behavior
prevent_change	Keep subscription on current plan until payment succeeds. Plan change remains pending.
apply_change	Apply plan change immediately regardless of payment outcome. This is the default.

If on_payment_failure is not specified, the behavior defaults to your business-level setting configured in the dashboard.

Discount Codes

You can apply one or more stacked discount codes when changing plans by passing the discount_codes array (max 20 entries, applied in array order). The singular discount_code field is deprecated but still works for existing integrations; it cannot be combined with discount_codes in the same request.

discount_codes value	Behavior
Not provided (null / omitted)	Existing discounts with preserve_on_plan_change=true are preserved if applicable to the new product.
[] (empty array)	All existing discounts are removed from the subscription.
["CODE_A", "CODE_B", ...]	Replaces any existing discounts with this stacked set, validated and applied in array order.

Use discount codes during plan changes to offer promotional pricing on upgrades, or pass codes when migrating customers to a new plan tier.

Use prevent_change for critical upgrades where you want to ensure payment before granting access to premium features.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

subscription_id · string · required

Subscription Id

Body

application/json

product_id · string · required

Unique identifier of the product to subscribe to

proration_billing_mode · enum<string> · required

Proration Billing Mode

Available options: prorated_immediately, full_immediately, difference_immediately, do_not_bill

quantity · integer<int32> · required

Number of units to subscribe for. Must be at least 1.

Required range: x >= 0

adaptive_currency_fees_inclusive · boolean | null

Whether adaptive currency fees should be included in the price (true) or added on top (false). If not specified, uses the subscription's stored setting.

addons · Attach Addon Request · object[] | null

Addons for the new plan. Note : Leaving this empty would remove any existing addons

Show child attributes

discount_code · string | null · deprecated

DEPRECATED: Use discount_codes instead. Cannot be used together with discount_codes.

discount_codes · string[] | null

Stacked discount codes to apply to the new plan. Max 20. Cannot be used together with discount_code. If provided, replaces any existing discount codes. Empty array removes all discounts. If not provided (None), existing discounts with preserve_on_plan_change=true are preserved.

effective_at · enum<string>

When to apply the plan change.

• immediately (default): Apply the plan change right away
• next_billing_date: Schedule the change for the next billing date

Available options: immediately, next_billing_date

metadata · object

Metadata for the payment. If not passed, the metadata of the subscription will be taken

Show child attributes

on_payment_failure · null | enum<string>

Controls behavior when the plan change payment fails.

• prevent_change: Keep subscription on current plan until payment succeeds
• apply_change (default): Apply plan change immediately regardless of payment outcome

If not specified, uses the business-level default setting.

Available options: prevent_change, apply_change

Response

200

Subscription plan changed. If on_payment_failure=prevent_change, the plan change is pending until payment succeeds.