메인 콘텐츠로 건너뛰기
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,
});

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

​
예약된 요금제 변경

요금제 변경이 언제 적용될지 제어하려면 effective_at 매개변수를 사용하세요:
값동작
immediately요금제 변경을 즉시 적용합니다. 기본값입니다.
next_billing_date다음 청구 날짜에 변경을 예약합니다. 고객은 청구 기간이 끝날 때까지 현재 요금제에 대한 접근을 유지합니다.
예약된 요금제 변경은 하향 조정에 이상적입니다 — 고객은 청구 기간이 끝날 때까지 현재 요금제 혜택을 유지하고, 자동으로 새로운 요금제로 전환됩니다.
요금제 변경이 적용되기 전에 예약된 요금제 변경을 취소하려면 예약된 요금제 변경 취소 엔드포인트를 사용하세요.

​
결제 실패 처리

요금제 변경 결제가 실패할 경우의 동작을 제어하려면 on_payment_failure 매개변수를 사용하세요:
값동작
prevent_change결제가 성공할 때까지 현재 요금제로 구독을 유지합니다. 요금제 변경은 대기 상태로 남습니다.
apply_change결제 결과에 상관없이 요금제 변경을 즉시 적용합니다. 기본값입니다.
on_payment_failure 매개변수가 지정되지 않으면, 대시보드에서 설정한 비즈니스 수준 설정이 기본값으로 사용됩니다.

​
할인 코드

요금제를 변경할 때 discount_code 매개변수를 전달하여 할인 코드를 적용할 수 있습니다.
시나리오동작
discount_code 제공됨할인을 검증하고 새로운 요금제에 적용합니다.
discount_code 제공되지 않음, 기존 할인 존재 preserve_on_plan_change=true새로운 제품에 적용 가능한 경우 기존 할인이 유지됩니다.
discount_code 제공되지 않음, 유지 가능한 할인 없음할인 적용 안됨.
업그레이드 시 프로모션 가격을 제공하기 위해 요금제 변경 시 할인 코드를 사용하거나, 고객을 새로운 요금제 계층으로 마이그레이션할 때 코드를 전달하세요.
프리미엄 기능에 대한 접근을 부여하기 전에 결제를 보장하려는 중요 업그레이드에는 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 April 20, 2026