메인 콘텐츠로 건너뛰기
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>"
  }
}
이 엔드포인트를 사용하면 구독을 업그레이드하거나 다운그레이드할 때 고객에게 정확히 청구될 금액을 표시하여 투명성을 높이고 지원 요청을 줄일 수 있습니다.

사용 사례

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