> ## 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` | 다음 청구 날짜에 변경을 예약합니다. 고객은 청구 기간이 끝날 때까지 현재 요금제에 대한 접근을 유지합니다. |
예약된 요금제 변경은 하향 조정에 이상적입니다 — 고객은 청구 기간이 끝날 때까지 현재 요금제 혜택을 유지하고, 자동으로 새로운 요금제로 전환됩니다.
요금제 변경이 적용되기 전에 예약된 요금제 변경을 취소하려면 [예약된 요금제 변경 취소](/api-reference/subscriptions/cancel-change-plan) 엔드포인트를 사용하세요.
## 결제 실패 처리
요금제 변경 결제가 실패할 경우의 동작을 제어하려면 `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`를 사용하세요.
## OpenAPI
````yaml post /subscriptions/{subscription_id}/change-plan
openapi: 3.1.0
info:
title: public
description: ''
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 1.106.2
servers:
- url: https://test.dodopayments.com/
description: Test Mode Server Host
- url: https://live.dodopayments.com/
description: Live Mode Server Host
security: []
tags:
- name: Products
- name: Payments
- name: Subscriptions
- name: Addons
- name: Customers
- name: Refunds
- name: Disputes
- name: Events
- name: License Keys
- name: Entitlements
- name: Licenses
- name: Discounts
- name: Meters
- name: Credit Entitlements
- name: Credit Entitlement Balances
- name: Outgoing Webhooks
- name: Checkout
- name: Webhook Events
- name: Payment Connector Webhooks
paths:
/subscriptions/{subscription_id}/change-plan:
post:
tags:
- Subscriptions
operationId: update_subscription_plan_handler
parameters:
- name: subscription_id
in: path
description: Subscription Id
required: true
schema:
type: string
example: sub_Iuaq622bbmmfOGrVTqdXv
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSubscriptionPlanReq'
required: true
responses:
'200':
description: >-
Subscription plan changed. If on_payment_failure=prevent_change, the
plan change is pending until payment succeeds.
'409':
description: >-
A pending plan change already exists for this subscription
(PendingPlanChangeExists)
'422':
description: Subscription is inactive or on-demand, plan change not supported
'500':
description: Something went wrong :(
security:
- API_KEY: []
x-codeSamples:
- lang: JavaScript
source: |-
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('sub_Iuaq622bbmmfOGrVTqdXv', {
product_id: 'product_id',
proration_billing_mode: 'prorated_immediately',
quantity: 0,
});
- lang: Python
source: |-
import os
from dodopayments import DodoPayments
client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"), # This is the default and can be omitted
)
client.subscriptions.change_plan(
subscription_id="sub_Iuaq622bbmmfOGrVTqdXv",
product_id="product_id",
proration_billing_mode="prorated_immediately",
quantity=0,
)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/dodopayments/dodopayments-go\"\n\t\"github.com/dodopayments/dodopayments-go/option\"\n)\n\nfunc main() {\n\tclient := dodopayments.NewClient(\n\t\toption.WithBearerToken(\"My Bearer Token\"),\n\t)\n\terr := client.Subscriptions.ChangePlan(\n\t\tcontext.TODO(),\n\t\t\"sub_Iuaq622bbmmfOGrVTqdXv\",\n\t\tdodopayments.SubscriptionChangePlanParams{\n\t\t\tUpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{\n\t\t\t\tProductID: dodopayments.F(\"product_id\"),\n\t\t\t\tProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),\n\t\t\t\tQuantity: dodopayments.F(int64(0)),\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
- lang: Java
source: >-
package com.dodopayments.api.example;
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import
com.dodopayments.api.models.subscriptions.SubscriptionChangePlanParams;
import
com.dodopayments.api.models.subscriptions.UpdateSubscriptionPlanReq;
public final class Main {
private Main() {}
public static void main(String[] args) {
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();
SubscriptionChangePlanParams params = SubscriptionChangePlanParams.builder()
.subscriptionId("sub_Iuaq622bbmmfOGrVTqdXv")
.updateSubscriptionPlanReq(UpdateSubscriptionPlanReq.builder()
.productId("product_id")
.prorationBillingMode(UpdateSubscriptionPlanReq.ProrationBillingMode.PRORATED_IMMEDIATELY)
.quantity(0)
.build())
.build();
client.subscriptions().changePlan(params);
}
}
- lang: Kotlin
source: >-
package com.dodopayments.api.example
import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import
com.dodopayments.api.models.subscriptions.SubscriptionChangePlanParams
import
com.dodopayments.api.models.subscriptions.UpdateSubscriptionPlanReq
fun main() {
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()
val params: SubscriptionChangePlanParams = SubscriptionChangePlanParams.builder()
.subscriptionId("sub_Iuaq622bbmmfOGrVTqdXv")
.updateSubscriptionPlanReq(UpdateSubscriptionPlanReq.builder()
.productId("product_id")
.prorationBillingMode(UpdateSubscriptionPlanReq.ProrationBillingMode.PRORATED_IMMEDIATELY)
.quantity(0)
.build())
.build()
client.subscriptions().changePlan(params)
}
- lang: Ruby
source: |-
require "dodopayments"
dodo_payments = Dodopayments::Client.new(
bearer_token: "My Bearer Token",
environment: "test_mode" # defaults to "live_mode"
)
result = dodo_payments.subscriptions.change_plan(
"sub_Iuaq622bbmmfOGrVTqdXv",
product_id: "product_id",
proration_billing_mode: :prorated_immediately,
quantity: 0
)
puts(result)
- lang: PHP
source: |-
subscriptions->changePlan(
'sub_Iuaq622bbmmfOGrVTqdXv',
productID: 'product_id',
prorationBillingMode: 'prorated_immediately',
quantity: 0,
adaptiveCurrencyFeesInclusive: true,
addons: [['addonID' => 'addon_id', 'quantity' => 0]],
discountCode: 'discount_code',
discountCodes: ['string'],
effectiveAt: 'immediately',
metadata: ['foo' => 'string'],
onPaymentFailure: 'prevent_change',
);
var_dump($result);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: C#
source: |-
using DodoPayments.Client;
using DodoPayments.Client.Models.Subscriptions;
DodoPaymentsClient client = new();
SubscriptionChangePlanParams parameters = new()
{
SubscriptionID = "sub_Iuaq622bbmmfOGrVTqdXv",
ProductID = "product_id",
ProrationBillingMode = ProrationBillingMode.ProratedImmediately,
Quantity = 0,
};
await client.Subscriptions.ChangePlan(parameters);
- lang: Rust
source: |-
use dodopayments::Client;
#[tokio::main]
async fn main() -> dodopayments::Result<()> {
let client = Client::from_env()?;
let subscription_id = "subscription_id";
let result = client
.subscriptions()
.change_plan()
.subscription_id(subscription_id)
.body(dodopayments::models::SubscriptionsChangePlanParams {
product_id: Some("product_id".to_string()),
proration_billing_mode: Some("prorated_immediately".to_string()),
quantity: Some(0),
..Default::default()
})
.await?;
println!("{result:?}");
Ok(())
}
components:
schemas:
UpdateSubscriptionPlanReq:
type: object
required:
- product_id
- quantity
- proration_billing_mode
properties:
adaptive_currency_fees_inclusive:
type:
- boolean
- 'null'
description: >-
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:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AttachAddonReq'
description: |-
Addons for the new plan.
Note : Leaving this empty would remove any existing addons
discount_code:
type:
- string
- 'null'
description: >-
DEPRECATED: Use discount_codes instead. Cannot be used together with
discount_codes.
deprecated: true
x-stainless-deprecation-message: Use `discount_id` instead.
discount_codes:
type:
- array
- 'null'
items:
type: string
description: >-
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:
$ref: '#/components/schemas/EffectiveAt'
description: |-
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
metadata:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Metadata'
description: >-
Metadata for the payment. If not passed, the metadata of the
subscription will be taken
on_payment_failure:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/OnPaymentFailure'
description: >-
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.
product_id:
type: string
description: Unique identifier of the product to subscribe to
proration_billing_mode:
$ref: '#/components/schemas/ProrationBillingMode'
description: Proration Billing Mode
quantity:
type: integer
format: int32
description: Number of units to subscribe for. Must be at least 1.
minimum: 0
AttachAddonReq:
type: object
title: Attach Addon Request
required:
- addon_id
- quantity
properties:
addon_id:
type: string
quantity:
type: integer
format: int32
description: Number of units of this addon.
minimum: 0
EffectiveAt:
type: string
description: When to apply a subscription plan change.
enum:
- immediately
- next_billing_date
Metadata:
type: object
title: Metadata
description: >-
Arbitrary key-value metadata. Values can be string, integer, number, or
boolean.
additionalProperties:
oneOf:
- type: string
title: String
- type: integer
title: Integer
format: int64
- type: number
title: Number
format: double
- type: boolean
title: Boolean
title: Metadata Value
description: Metadata value can be a string, integer, number, or boolean
OnPaymentFailure:
type: string
description: >-
Specifies how to handle subscription plan changes when payment fails.
This enum controls whether the subscription should be updated
immediately
or only after payment succeeds.
enum:
- prevent_change
- apply_change
ProrationBillingMode:
type: string
title: Proration Billing Mode
enum:
- prorated_immediately
- full_immediately
- difference_immediately
- do_not_bill
securitySchemes:
API_KEY:
type: http
scheme: bearer
````