跳转到主要内容
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_codes 数组（最多 20 个条目，按数组顺序应用）应用一个或多个叠加折扣码。单一的 discount_code 字段已弃用，但现有集成仍可使用；无法在同一请求中与 discount_codes 结合使用。
discount_codes 值行为
未提供 (null / 省略)如果适用于新产品，现有折扣与 preserve_on_plan_change=true 保持不变。
[] (空数组)所有现有折扣从订阅中移除。
["CODE_A", "CODE_B", ...]用这个叠加集合替换任何现有折扣，按数组顺序验证并应用。
在计划更改期间使用折扣码，以便为升级提供促销定价，或在将客户迁移到新计划层时传递代码。
对于需要确保支付后才能授予高级功能访问权限的重要升级，使用 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
​
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

​
discount_code
string | null
已弃用

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
可用选项:
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 May 22, 2026