요금제 변경 미리보기 - 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>"
  }
}

이 엔드포인트를 사용하여 고객에게 구독을 업그레이드하거나 다운그레이드할 때 청구될 금액을 정확히 보여줌으로써 투명성을 높이고 지원 요청을 줄일 수 있습니다.

사용 사례

체크아웃 확인: 고객이 요금제를 변경하기 전에 할당된 요금을 표시합니다.
가격 계산기: 애플리케이션에서 업그레이드/다운그레이드 계산기를 구축합니다.
고객 셀프 서비스: 고객이 정확한 가격으로 요금제 옵션을 탐색할 수 있도록 합니다.
할인 검증: 할인 코드가 요금제 변경 가격에 미치는 영향을 미리 봅니다.

You can include a discount_code in the preview request to see how the discount affects the immediate charge and new plan pricing before committing to the change.

응답 필드

미리보기 응답에는 다음이 포함됩니다:

필드	설명
`immediate_charge`	즉시 생성될 요금으로, 품목 및 요약 포함
`new_plan`	요금제 변경 후 어떻게 보일지를 보여주는 전체 구독 객체

The immediate_charge.summary contains the total amount that would be charged. Use this to display pricing to your customers before they confirm the plan 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

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 April 8, 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>"
  }
}

​사용 사례

​응답 필드

인증

경로 매개변수

본문

응답

사용 사례

응답 필드