メインコンテンツへスキップ
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,
});

​
支払い失敗の処理

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 1, 2026