メインコンテンツへスキップ
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 value動作
提供されていない場合（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