メインコンテンツへスキップ
POST
/
subscriptions
/
{subscription_id}
/
change-plan
/
preview
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.previewChangePlan('subscription_id', {
  product_id: 'product_id',
  proration_billing_mode: 'prorated_immediately',
  quantity: 0,
});

console.log(response.immediate_charge);
{
  "immediate_charge": {
    "effective_at": "2023-11-07T05:31:56Z",
    "line_items": [
      {
        "currency": "AED",
        "id": "<string>",
        "product_id": "<string>",
        "proration_factor": 123,
        "quantity": 123,
        "tax_inclusive": true,
        "type": "subscription",
        "unit_price": 123,
        "description": "<string>",
        "name": "<string>",
        "tax": 123,
        "tax_rate": 123
      }
    ],
    "summary": {
      "currency": "AED",
      "customer_credits": 123,
      "settlement_amount": 123,
      "settlement_currency": "AED",
      "total_amount": 123,
      "settlement_tax": 123,
      "tax": 123
    }
  },
  "new_plan": {
    "addons": [
      {
        "addon_id": "<string>",
        "quantity": 123
      }
    ],
    "billing": {
      "country": "AF",
      "city": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipcode": "<string>"
    },
    "cancel_at_next_billing_date": true,
    "created_at": "2023-11-07T05:31:56Z",
    "credit_entitlement_cart": [
      {
        "credit_entitlement_id": "<string>",
        "credit_entitlement_name": "<string>",
        "credits_amount": "<string>",
        "overage_balance": "<string>",
        "overage_behavior": "forgive_at_reset",
        "overage_enabled": true,
        "product_id": "<string>",
        "remaining_balance": "<string>",
        "rollover_enabled": true,
        "unit": "<string>",
        "expires_after_days": 123,
        "low_balance_threshold_percent": 123,
        "max_rollover_count": 123,
        "overage_limit": "<string>",
        "rollover_percentage": 123,
        "rollover_timeframe_count": 123,
        "rollover_timeframe_interval": "Day"
      }
    ],
    "currency": "AED",
    "customer": {
      "customer_id": "<string>",
      "email": "<string>",
      "name": "<string>",
      "metadata": {},
      "phone_number": "<string>"
    },
    "metadata": {},
    "meter_credit_entitlement_cart": [
      {
        "credit_entitlement_id": "<string>",
        "meter_id": "<string>",
        "meter_name": "<string>",
        "meter_units_per_credit": "<string>",
        "product_id": "<string>"
      }
    ],
    "meters": [
      {
        "currency": "AED",
        "free_threshold": 123,
        "measurement_unit": "<string>",
        "meter_id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "price_per_unit": "10.50"
      }
    ],
    "next_billing_date": "2023-11-07T05:31:56Z",
    "on_demand": true,
    "payment_frequency_count": 123,
    "payment_frequency_interval": "Day",
    "previous_billing_date": "2023-11-07T05:31:56Z",
    "product_id": "<string>",
    "quantity": 123,
    "recurring_pre_tax_amount": 123,
    "status": "pending",
    "subscription_id": "<string>",
    "subscription_period_count": 123,
    "subscription_period_interval": "Day",
    "tax_inclusive": true,
    "trial_period_days": 123,
    "cancelled_at": "2023-11-07T05:31:56Z",
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "expires_at": "2023-11-07T05:31:56Z",
    "payment_method_id": "<string>",
    "scheduled_change": {
      "addons": [
        {
          "addon_id": "<string>",
          "name": "<string>",
          "quantity": 123
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "effective_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "product_id": "<string>",
      "quantity": 123,
      "product_description": "<string>",
      "product_name": "<string>"
    },
    "tax_id": "<string>"
  }
}
このエンドポイントを使用して、サブスクリプションのアップグレードやダウングレード時に顧客に正確な料金を示します。これにより透明性が向上し、サポートへの問い合わせを減らすことができます。

ユースケース

  • チェックアウト確認: 顧客がプラン変更を確認する前に、日割り計算された料金を表示する
  • 価格計算機: アプリケーション内でアップグレード/ダウングレードの計算機を構築する
  • 顧客セルフサービス: 顧客が正確な価格でプランオプションを探ることができるようにする
  • 割引検証: 割引コードがプラン変更の価格にどのように影響するかをプレビューする
/* LOCKED_PATTERN_6fa96040307d68e9fa44436559d63ee8 / 変更を確定する前に、割引が即時請求と新しいプランの価格にどのように影響するかを見るために、プレビューリクエストにdiscount_codeを含めることができます。 / LOCKED_PATTERN_07427f62e4e59df6149fbd24d60de439 */

レスポンスフィールド

プレビュー応答には次のものが含まれます:
フィールド説明
immediate_charge行項目とサマリーを含め、即時に作成される料金
new_planプラン変更後の状態を示す完全なサブスクリプションオブジェクト
/* LOCKED_PATTERN_317ec56569e36d0c9e56c2648890a76e / immediate_charge.summaryは請求される合計金額を含みます。顧客がプラン変更を確認する前に価格を表示するために使用してください。 / LOCKED_PATTERN_4dec52ce04aa8849a8a60508baae30ae */

承認

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

レスポンス

Preview of subscription plan change

immediate_charge
object
必須
new_plan
object
必須

Response struct representing subscription details

Last modified on April 1, 2026