跳转到主要内容
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,
});

​
计划更改安排

使用 effective_at 参数来控制计划更改生效的时间：
值行为
immediately立即应用计划更改。这是默认设置。
next_billing_date将更改安排在下一个账单日期。客户在账单期结束前保留当前计划的访问权限。
计划更改安排对于降级非常理想——客户在账单期结束前保留其当前计划的福利，然后自动切换到新计划。
要在生效前取消计划变更，使用 取消计划变更 端点。

​
支付失败处理

使用 on_payment_failure 参数来控制在计划更改支付失败时会发生什么：
值行为
prevent_change保留在当前计划，直到支付成功。计划更改保持待定状态。
apply_change无论支付结果如何，立即应用计划更改。这是默认设置。
如果未指定 on_payment_failure，则默认行为为您在仪表板中配置的业务级别设置。

​
优惠码

更改计划时，可以通过传递 discount_code 参数来应用优惠码。
场景行为
提供了 discount_code验证并将折扣适用于新计划。
未提供 discount_code，但存在 preserve_on_plan_change=true 的现有折扣如果适用于新产品，则保留现有折扣。
未提供 discount_code，无可保留折扣无折扣应用。
在计划更改时使用优惠码，以便在升级时提供促销价格，或在将客户迁移到新计划层时传递代码。
对于需要确保支付后才能授予高级功能访问权限的重要升级，使用 prevent_change。

授权

​
Authorization
string
header
必填

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

路径参数

​
subscription_id
string
必填

Subscription Id

请求体

application/json
​
product_id
string
必填

Unique identifier of the product to subscribe to

​
proration_billing_mode
enum<string>
必填

Proration Billing Mode

可用选项:
prorated_immediately,
full_immediately,
difference_immediately,
do_not_bill
​
quantity
integer<int32>
必填

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

必填范围: x >= 0
​
addons
Attach Addon Request · object[] | null

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

​
discount_code
string | null

Optional discount code to apply to the new plan. If provided, validates and applies the discount to the plan change. If not provided and the subscription has an existing discount with preserve_on_plan_change=true, the existing discount will be preserved (if applicable to the new product).

​
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
可用选项:
immediately,
next_billing_date
​
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.

可用选项:
prevent_change,
apply_change

响应

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

Last modified on April 20, 2026