> ## 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.

# Change Plan

> Modify an existing subscription's plan, enabling both upgrades and downgrades to different pricing tiers.<br/><br/>Note&colon; This will use the existing payment information of the customer to upgrade/downgrade the plan.

## Scheduled Plan Changes

Use the `effective_at` parameter to control when the plan change takes effect:

| Value               | Behavior                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `immediately`       | Apply the plan change right away. This is the default.                                                                          |
| `next_billing_date` | Schedule the change for the next billing date. The customer retains access to their current plan until the billing period ends. |

<Info>
  Scheduled plan changes are ideal for downgrades — customers keep their current plan benefits until the end of the billing period, then automatically switch to the new plan.
</Info>

To cancel a scheduled plan change before it takes effect, use the [Cancel Scheduled Plan Change](/api-reference/subscriptions/cancel-change-plan) endpoint.

## Payment Failure Handling

Use the `on_payment_failure` parameter to control what happens when the plan change payment fails:

| Value            | Behavior                                                                               |
| ---------------- | -------------------------------------------------------------------------------------- |
| `prevent_change` | Keep subscription on current plan until payment succeeds. Plan change remains pending. |
| `apply_change`   | Apply plan change immediately regardless of payment outcome. This is the default.      |

<Info>
  If `on_payment_failure` is not specified, the behavior defaults to your business-level setting configured in the dashboard.
</Info>

## Discount Codes

You can apply one or more **stacked discount codes** when changing plans by passing the `discount_codes` array (max 20 entries, applied in array order). The singular `discount_code` field is deprecated but still works for existing integrations; it cannot be combined with `discount_codes` in the same request.

| `discount_codes` value          | Behavior                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Not provided (`null` / omitted) | Existing discounts with `preserve_on_plan_change=true` are preserved if applicable to the new product. |
| `[]` (empty array)              | **All** existing discounts are removed from the subscription.                                          |
| `["CODE_A", "CODE_B", ...]`     | Replaces any existing discounts with this stacked set, validated and applied in array order.           |

<Tip>
  Use discount codes during plan changes to offer promotional pricing on upgrades, or pass codes when migrating customers to a new plan tier.
</Tip>

<Tip>
  Use `prevent_change` for critical upgrades where you want to ensure payment before granting access to premium features.
</Tip>


## 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.105.0
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
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
      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('subscription_id', {
              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="subscription_id",
                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\"subscription_id\",\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("subscription_id")
                        .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("subscription_id")
                    .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(
              "subscription_id",
              product_id: "product_id",
              proration_billing_mode: :prorated_immediately,
              quantity: 0
            )

            puts(result)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Dodopayments\Client;
            use Dodopayments\Core\Exceptions\APIException;

            $client = new Client(
              bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
              environment: 'test_mode',
            );

            try {
              $result = $client->subscriptions->changePlan(
                'subscription_id',
                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 = "subscription_id",
                ProductID = "product_id",
                ProrationBillingMode = ProrationBillingMode.ProratedImmediately,
                Quantity = 0,
            };

            await client.Subscriptions.ChangePlan(parameters);
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
          minimum: 0
    EffectiveAt:
      type: string
      description: When to apply a subscription plan change.
      enum:
        - immediately
        - next_billing_date
    Metadata:
      type: object
      additionalProperties:
        type: string
      propertyNames:
        type: string
    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

````