プラン変更のプレビュー - Dodo Payments Documentation

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": [
      {
        "id": "<string>",
        "product_id": "<string>",
        "proration_factor": 123,
        "quantity": 123,
        "tax_inclusive": true,
        "unit_price": 123,
        "description": "<string>",
        "name": "<string>",
        "tax": 123,
        "tax_rate": 123
      }
    ],
    "summary": {
      "customer_credits": 123,
      "settlement_amount": 123,
      "total_amount": 123,
      "settlement_tax": 123,
      "tax": 123
    }
  },
  "new_plan": {
    "addons": [
      {
        "addon_id": "<string>",
        "quantity": 123
      }
    ],
    "billing": {
      "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_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
      }
    ],
    "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": [
      {
        "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,
    "previous_billing_date": "2023-11-07T05:31:56Z",
    "product_id": "<string>",
    "quantity": 123,
    "recurring_pre_tax_amount": 123,
    "subscription_id": "<string>",
    "subscription_period_count": 123,
    "tax_inclusive": true,
    "trial_period_days": 123,
    "cancellation_comment": "<string>",
    "cancelled_at": "2023-11-07T05:31:56Z",
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "customer_business_name": "<string>",
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "discounts": [
      {
        "amount": 123,
        "business_id": "<string>",
        "code": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "discount_id": "<string>",
        "metadata": {},
        "position": 123,
        "preserve_on_plan_change": true,
        "restricted_to": [
          "<string>"
        ],
        "times_used": 123,
        "cycles_remaining": 123,
        "expires_at": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "subscription_cycles": 123,
        "usage_limit": 123
      }
    ],
    "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>"
  }
}

このエンドポイントを使用して、サブスクリプションのアップグレードやダウングレード時に顧客に正確な料金を示します。これにより透明性が向上し、サポートへの問い合わせを減らすことができます。

ユースケース

チェックアウト確認: 顧客がプラン変更を確認する前に比例配分された料金を表示
料金計算機: アプリケーションでアップグレード/ダウングレード計算機を構築
顧客セルフサービス: 顧客が正確な価格でプランオプションを探求できるように
割引検証: 重ね合わせた割引コードがプラン変更の価格にどのように影響するかをプレビュー

変更を確定する前に、スタックされた割引が即時の請求および新しいプランの価格にどのように影響するかを見るために、プレビューリクエストで discount_codes （20個までのコードの配列、順番に適用）を含めることができます。単一の discount_code フィールドは廃止予定ですが、後方互換性のためにまだサポートされています。今後は discount_codes をお勧めします。

レスポンスフィールド

プレビュー応答には次のものが含まれます：

フィールド	説明
`immediate_charge`	行項目とサマリーを含め、即時に作成される料金
`new_plan`	プラン変更後の状態を示す完全なサブスクリプションオブジェクト

immediate_charge.summaryは請求される合計金額を含みます。顧客がプラン変更を確認する前に価格を表示するために使用してください。

承認

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

Show child attributes

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

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

レスポンス

Preview of subscription plan change

immediate_charge

object

必須

Show child attributes

new_plan

object

必須

Response struct representing subscription details

Show child attributes

Last modified on May 22, 2026

予定されたプラン変更のキャンセルサブスクリプションの予定されたプラン変更をキャンセルします。

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": [
      {
        "id": "<string>",
        "product_id": "<string>",
        "proration_factor": 123,
        "quantity": 123,
        "tax_inclusive": true,
        "unit_price": 123,
        "description": "<string>",
        "name": "<string>",
        "tax": 123,
        "tax_rate": 123
      }
    ],
    "summary": {
      "customer_credits": 123,
      "settlement_amount": 123,
      "total_amount": 123,
      "settlement_tax": 123,
      "tax": 123
    }
  },
  "new_plan": {
    "addons": [
      {
        "addon_id": "<string>",
        "quantity": 123
      }
    ],
    "billing": {
      "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_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
      }
    ],
    "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": [
      {
        "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,
    "previous_billing_date": "2023-11-07T05:31:56Z",
    "product_id": "<string>",
    "quantity": 123,
    "recurring_pre_tax_amount": 123,
    "subscription_id": "<string>",
    "subscription_period_count": 123,
    "tax_inclusive": true,
    "trial_period_days": 123,
    "cancellation_comment": "<string>",
    "cancelled_at": "2023-11-07T05:31:56Z",
    "custom_field_responses": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "customer_business_name": "<string>",
    "discount_cycles_remaining": 123,
    "discount_id": "<string>",
    "discounts": [
      {
        "amount": 123,
        "business_id": "<string>",
        "code": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "discount_id": "<string>",
        "metadata": {},
        "position": 123,
        "preserve_on_plan_change": true,
        "restricted_to": [
          "<string>"
        ],
        "times_used": 123,
        "cycles_remaining": 123,
        "expires_at": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "subscription_cycles": 123,
        "usage_limit": 123
      }
    ],
    "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>"
  }
}

​ユースケース

​レスポンスフィールド

承認

パスパラメータ

ボディ

レスポンス

ユースケース

レスポンスフィールド