Skip to main content
POST
/
subscriptions
/
{subscription_id}
/
change-plan
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,
});

​
Payment Failure Handling

Use the on_payment_failure parameter to control what happens when the plan change payment fails:
ValueBehavior
prevent_changeKeep subscription on current plan until payment succeeds. Plan change remains pending.
apply_changeApply 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.
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
​
quantity
integer<int32>
required

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

Required range: x >= 0
​
addons
Attach Addon Request · object[] | null

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

​
metadata
object

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

​
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

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