> ## 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.
# Ändra plan
> Ändra en befintlig abonnemangsplan, vilket möjliggör både uppgraderingar och nedgraderingar till olika prisklasser.
Observera: Detta kommer att använda den befintliga betalningsinformationen för kunden för att uppgradera/nedgradera planen.
## Schemalagda ändringar av plan
Använd parametern `effective_at` för att kontrollera när planändringen träder i kraft:
| Värde | Beteende |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `immediately` | Tillämpa planändringen direkt. Detta är standard. |
| `next_billing_date` | Planera ändringen till nästa faktureringsdatum. Kunden behåller tillgången till sin nuvarande plan tills faktureringsperioden slutar. |
Schemalagda planändringar är idealiska för nedgradering — kunder behåller sina nuvarande planförmåner till slutet av faktureringsperioden, och byter sedan automatiskt till den nya planen.
För att avbryta en schemalagd planändring innan den träder i kraft, använd slutpunkten [Cancel Scheduled Plan Change](/api-reference/subscriptions/cancel-change-plan).
## Hantering av betalningsfel
Använd parametern `on_payment_failure` för att kontrollera vad som händer när betalningen för planändringen misslyckas:
| Värde | Beteende |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `prevent_change` | Behåll abonnemanget på nuvarande plan tills betalningen lyckas. Planändring förblir väntande. |
| `apply_change` | Tillämpa planändringen omedelbart oavsett betalningsresultat. Detta är standard. |
Om `on_payment_failure` inte anges, är beteendet förvalt till din affärsnivåinställning som konfigureras i instrumentpanelen.
## Rabattkoder
Du kan använda en eller flera **staplade rabattkoder** när du byter planer genom att skicka `discount_codes`-arrayen (max 20 poster, tillämpas i arrayordning). Det enkla fältet `discount_code` är föråldrat men fungerar fortfarande för befintliga integrationer; det kan inte kombineras med `discount_codes` i samma förfrågan.
| `discount_codes`-värde | Beteende |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Ej angivet (`null` / utelämnad) | Befintliga rabatter med `preserve_on_plan_change=true` bevaras om tillämpligt för den nya produkten. |
| `[]` (tom array) | **Alla** befintliga rabatter tas bort från prenumerationen. |
| `["CODE_A", "CODE_B", ...]` | Ersätter eventuella befintliga rabatter med denna staplade uppsättning, validerad och tillämpad i arrayordning. |
Använd rabattkoder vid planändringar för att erbjuda kampanjpriser på uppgraderingar, eller skicka koder när kunder migreras till en ny plannivå.
Använd `prevent_change` för kritiska uppgraderingar där du vill säkerställa betalning innan du ger åtkomst till premiumfunktioner.
## 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.11
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
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
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
````