更改计划

修改现有订阅的计划，支持升级和降级到不同的定价层级。

注意：默认情况下，此操作使用客户现有的付款信息。将 collect_via_payment_link 设置为 true 可改为通过托管结账页面收费。

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
});

const response = await client.subscriptions.changePlan('sub_Iuaq622bbmmfOGrVTqdXv', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

console.log(response.payment_id);

200

{
  "client_secret": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "payment_id": "<string>",
  "payment_link": "<string>"
}

​

计划更改安排

使用 effective_at 参数来控制计划更改生效的时间：

值	行为
immediately	立即应用计划更改。这是默认设置。
next_billing_date	将更改安排在下一个账单日期。客户在账单期结束前保留当前计划的访问权限。

计划更改安排对于降级非常理想——客户在账单期结束前保留其当前计划的福利，然后自动切换到新计划。

要在生效前取消计划变更，使用 取消计划变更 端点。

​

支付失败处理

使用 on_payment_failure 参数来控制在计划更改支付失败时会发生什么：

值	行为
prevent_change	在付款成功前保持订阅使用当前计划。计划变更保持待处理状态。
apply_change	无论付款结果如何，立即应用计划变更。

如果未指定 on_payment_failure，则默认行为为您在仪表板中配置的业务级别设置。

​

通过 Payment Link 收款

将 collect_via_payment_link 设置为 true，可将客户转到托管结账页面，而不是使用其已保存的付款方式进行收费。然后，响应会包含 payment_id、payment_link、client_secret 和 expires_on — 将客户重定向到 payment_link 以完成付款。

这需要满足以下条件：

要求	原因
商户已启用 allow_plan_change_via_payment_link 功能	默认关闭；可在 Settings → Subscriptions → Collect Plan Change Payments by Payment Link 中开启。
effective_at: immediately	计划变更在生效前不会收取任何费用，因此目前还没有可通过结账流程收取的款项。
on_payment_failure: prevent_change	在结账付款实际成功之前，订阅必须保持当前计划。请在请求中显式发送该字段。

不符合这些条件的请求会返回 422。在链接付款完成前，订阅会保持当前计划；后续再次发送 change-plan 请求时会返回 409，除非设置了 cancel_older_payment_link。

​

付款后重定向

设置 return_url，以便在客户支付链接后将其返回到您的网站。重定向会将 subscription_id、payment_id 和 status 作为查询参数添加。

• status 表示计划变更付款的状态，而不是订阅的状态。
• 付款失败时，订阅会在当前计划上保持 active 状态。要重试，请再次调用 change-plan 以获取新链接。
• 收到付款 webhook 后，新计划可能会在重定向后不久生效。

return_url 需要 collect_via_payment_link: true。缺少该字段时，请求会返回 422。

​

替换待处理的付款链接

如果客户未付款就离开了结账页面，请在下一次 change-plan 请求中将 cancel_older_payment_link 设置为 true。Dodo Payments 会取消未付款的链接，而新的计划变更会替换待处理的变更。已取消的链接将不再接受付款。

请求会在链接取消前进行验证，因此无效请求不会影响客户的链接。仅当客户尚未开始付款时，链接才会被取消：

之前的付款状态	响应
未打开、已打开但未付款，或已拒付	200，并返回新链接
客户当前正在付款，例如正在进行 3D Secure 验证	409 PLAN_CHANGE_PAYMENT_IN_PROGRESS。请在付款完成或失败后重试。
已付款	409 PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED。之前的计划变更会生效。
无法取消链接	503 PLAN_CHANGE_LINK_CANCEL_FAILED。没有任何变更，因此可以重试。

每个 change-plan 请求都会生成自己的发票。被替换的计划变更及其发票会被取消。

有关完整流程，包括付款被拒、替换待处理链接以及链接过期时的处理方式，请参阅 订阅升级与降级指南。

​

折扣代码

更改计划时，可以通过传递 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, prorated_immediately_keep_cycle

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

Show child attributes

cancel_older_payment_link · boolean

Cancel the payment link of a pending plan change, so that this change can replace it.

The link is cancelled only if the customer has not started to pay. A paid or in-progress payment gives a 409. A failed cancel gives a 503, and a retry is safe.

The request is validated before the cancel. A later failure, for example an amount below the minimum, leaves the subscription on its current plan with no open link. A retry is safe.

The preview route shares this request body and ignores this field.

cancel_scheduled_change_plan · boolean

Replace a scheduled plan change with this one.

The scheduled change is cancelled by the transaction that applies this change. A change that never applies leaves the schedule in place.

effective_at: next_billing_date is allowed. The new schedule then replaces the old one in the request transaction.

A pending plan change still gets a 409. This field does not affect it.

The preview route shares this request body, so a preview that sets this field also passes the scheduled-change 409.

collect_via_payment_link · boolean

Collect the plan-change amount with a payment link. The customer then pays on a checkout page.

The business needs the allow_plan_change_via_payment_link capability. The request needs effective_at: immediately. The request also needs on_payment_failure: prevent_change.

The preview route shares this request body and ignores this field.

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 · null | 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.

可用选项: prevent_change, apply_change

return_url · string | null

The URL that receives the customer after they pay the payment link. Needs collect_via_payment_link: true. Without it, the request gets a 422. A change that collects no money issues no link and does not use the URL. The preview route validates this field but does not use it.

The redirect adds subscription_id, payment_id and status. The status value is the status of the plan-change payment. It is not the status of the subscription. When that payment fails, the subscription stays active on its current plan. To try again, call this endpoint again to get a new link. The new plan can apply after the redirect, when the payment webhook arrives.

响应

200

application/json

Subscription plan changed. A link request can return checkout details. A pending plan change applies after payment succeeds.

Handles for a hosted checkout page that settles a plan change.

The four fields repeat UpdatePaymentMethodResponse and a subset of CreateSubscriptionResponse. A shared type would rename the generated SDK types for all three routes, so each route keeps its own.

client_secret · string | null

Client secret for an embedded checkout.

expires_on · string<date-time> | null

When the link stops working.

payment_id · string | null

Id of the payment that settles the plan change.

payment_link · string | null

Checkout page URL. Give this to the customer.