플랜 변경

기존 구독의 플랜을 수정하여 다양한 가격대의 업그레이드 및 다운그레이드를 가능하게 합니다.

참고: 이 작업은 고객의 기존 결제 정보를 사용하여 플랜을 업그레이드/다운그레이드합니다.

POST /subscriptions/{subscription_id}/change-plan

JavaScript

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,
});

​

예약된 요금제 변경

요금제 변경이 언제 적용될지 제어하려면 effective_at 매개변수를 사용하세요:

값	동작
immediately	요금제 변경을 즉시 적용합니다. 기본값입니다.
next_billing_date	다음 청구 날짜에 변경을 예약합니다. 고객은 청구 기간이 끝날 때까지 현재 요금제에 대한 접근을 유지합니다.

예약된 요금제 변경은 하향 조정에 이상적입니다 — 고객은 청구 기간이 끝날 때까지 현재 요금제 혜택을 유지하고, 자동으로 새로운 요금제로 전환됩니다.

요금제 변경이 적용되기 전에 예약된 요금제 변경을 취소하려면 예약된 요금제 변경 취소 엔드포인트를 사용하세요.

​

결제 실패 처리

요금제 변경 결제가 실패할 경우의 동작을 제어하려면 on_payment_failure 매개변수를 사용하세요:

값	동작
prevent_change	결제가 성공할 때까지 현재 요금제로 구독을 유지합니다. 요금제 변경은 대기 상태로 남습니다.
apply_change	결제 결과에 상관없이 요금제 변경을 즉시 적용합니다. 기본값입니다.

on_payment_failure 매개변수가 지정되지 않으면, 대시보드에서 설정한 비즈니스 수준 설정이 기본값으로 사용됩니다.

​

할인 코드

계획을 변경할 때 인라인 코드 배열(discount_codes)을 전달하여 하나 이상의 중첩된 할인 코드를 적용할 수 있습니다(최대 20개 항목, 배열 순서로 적용). 단일 필드(discount_code)는 더 이상 사용되지 않지만 기존 통합에서는 여전히 작동합니다. 해당 필드는 동일한 요청에서 discount_codes와 함께 사용할 수 없습니다.

discount_codes 값	동작
제공되지 않음 (null / 생략됨)	새로운 제품에 적용 가능한 경우 preserve_on_plan_change=true으로 기존 할인이 유지됩니다.
[] (빈 배열)	모든 기존 할인이 구독에서 제거됩니다.
["CODE_A", "CODE_B", ...]	배열 순서로 검증 및 적용된 이 중첩 세트로 기존 할인을 대체합니다.

플랜 변경 시 할인 코드를 사용하여 업그레이드에 대한 프로모션 가격을 제공하거나, 고객을 새로운 플랜 계층으로 마이그레이션할 때 코드를 전달하십시오.

프리미엄 기능에 대한 접근을 부여하기 전에 결제를 보장하려는 중요 업그레이드에는 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

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

응답

200

Subscription plan changed. If on_payment_failure=prevent_change, the plan change is pending until payment succeeds.