Subscription Upgrade & Downgrade Guide - Dodo Payments Documentation

Change Plan API

Full API docs for updating subscriptions.

Plan Change Preview

See charge amounts before changing plans.

Integration Guide

Step-by-step subscription setup.

Vad är en uppgradering eller nedgradering av en prenumeration?

Ändra kundens prenumerationsplan för att flytta dem mellan nivåer, justera kvantiteten för sätesbaserade produkter eller migrera till en ny produkt. API:t beräknar automatiskt proportionella belopp och debiteringar baserat på det valda debiteringsläget.

Plan changes can trigger an immediate charge depending on the proration mode you choose.

När ska planändringar användas?

Upgrade when a customer needs more features, usage, or seats
Downgrade when usage decreases
Migrate users to a new product or price without cancelling their subscription

Plan Change Flow

Prerequisites

Before implementing subscription plan changes, ensure you have:

A Dodo Payments merchant account with active subscription products
API credentials (API key and webhook secret key) from the dashboard
An existing active subscription to modify
Webhook endpoint configured to handle subscription events

Detaljerade konfigurationsinstruktioner finns i integrationsguiden.

Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

Understand Plan Change Requirements

Before implementing, determine:

Which subscription products can be changed to which others
What proration mode fits your business model
How to handle failed plan changes gracefully
Which webhook events to track for state management

Test plan changes thoroughly in test mode before implementing in production.

Choose Your Proration Strategy

Select the billing approach that aligns with your business needs:

prorated_immediately
difference_immediately
full_immediately
do_not_bill

Bäst för: SaaS-applikationer som vill kreditera oanvänd tid på den gamla planen.

Krediterar den oanvända delen av den aktuella cykeln, proportionellt efter återstående tid
Debiterar sedan en hel cykel för den nya planen – priset för den nya planen proportioneras aldrig
Nettodebitering = hel ny cykel − (återstående andel × hel gammal cykel)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

obligatorisk

The ID of the active subscription to modify.

string

obligatorisk

Det nya produkt-ID:t som prenumerationen ska ändras till.

integer

obligatorisk

Antal enheter för den nya planen (för sätesbaserade produkter).

string

obligatorisk

Hur omedelbar debitering ska hanteras: prorated_immediately, full_immediately, difference_immediately eller do_not_bill.

array

Valfria tillägg för den nya planen. Om du utelämnar detta fält, skickar null eller skickar en tom array tas alla befintliga tillägg bort, så inkludera befintliga tillägg för att behålla dem.

string

Styr beteendet när betalningen för planändringen misslyckas:

prevent_change: Behåll prenumerationen på den aktuella planen tills betalningen lyckas
apply_change (standard): Tillämpa planändringen omedelbart oavsett betalningsresultat

If not specified, uses the business-level default setting.

boolean

Samla in beloppet för planändringen via en betalningslänk i stället för att debitera prenumerationens sparade betalningsmetod. Kunden betalar på en hostad kassasida.Kräver företagets allow_plan_change_via_payment_link-funktion (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately och on_payment_failure: prevent_change. Se Collecting Payment via a Checkout Link. Ignoreras av förhandsgranskningsrutten.

string

URL:en som tar emot kunden efter att betalningen via betalningslänken har genomförts. Omdirigeringen lägger till subscription_id, payment_id och status. Kräver collect_via_payment_link: true; annars misslyckas begäran med 422. Se Omdirigera kunden efter betalning.

boolean

standard:"false"

Avbryt den obetalda betalningslänken för en väntande planändring, så att denna begäran ersätter den. En betald betalning eller en betalning som pågår returnerar 409. Se Ersätta en väntande betalningslänk. Ignoreras av preview-routen.

array

Valfria staplade rabattkoder som ska tillämpas på den nya planen (max 20, tillämpas i arrayordning). Beteendet beror på vad du skickar:

Inte angivet / null — befintliga rabatter med preserve_on_plan_change=true bevaras om de gäller för den nya produkten.
[] (tom array) — tar bort alla befintliga rabatter från prenumerationen.
["CODE_A", "CODE_B", ...] — ersätter alla befintliga rabatter med denna staplade uppsättning.

string

föråldrad

Föråldrat — använd helst discount_codes för nya integrationer. Fältet fungerar fortfarande av bakåtkompatibilitetsskäl, men kan inte kombineras med discount_codes i samma begäran.

string

standard:"immediately"

När planändringen ska tillämpas:

immediately (standard): Tillämpa planändringen omedelbart
next_billing_date: Schemalägg ändringen till nästa faktureringsdatum. Kunden behåller sin aktuella plan tills faktureringsperioden är slut. Använd detta för nedgraderingar så att kunderna behåller fördelarna med sin aktuella plan fram till faktureringsperiodens slut.

Handle Webhook Events

Konfigurera webhook-hantering för att följa resultatet av planändringar:

subscription.active: Planändringen lyckades, prenumerationen uppdaterades
subscription.plan_changed: Prenumerationsplanen ändrades (uppgradering/nedgradering/uppdatering av tillägg)
subscription.on_hold: Debiteringen för planändringen misslyckades, förnyelser stoppades
payment.succeeded: Den omedelbara debiteringen för planändringen lyckades
payment.failed: Den omedelbara debiteringen misslyckades

Verifiera alltid webhook-signaturer och implementera idempotent händelsehantering.

Update Your Application State

Uppdatera din applikation baserat på webhook-händelser:

Ge eller återkalla funktioner baserat på den nya planen
Uppdatera kundpanelen med information om den nya planen
Skicka bekräftelsemejl om planändringar
Logga faktureringsändringar för granskningsändamål

Test and Monitor

Testa implementationen noggrant:

Testa alla prorateringslägen med olika scenarier
Kontrollera att webhook-hanteringen fungerar korrekt
Övervaka hur ofta planändringar lyckas
Konfigurera aviseringar för misslyckade planändringar

Din implementation av planändringar för prenumerationer är nu klar för produktionsanvändning.

Förhandsvisa planändringar

Innan du genomför en planändring kan du använda Preview API för att visa kunderna exakt vad de kommer att debiteras:

Node.js SDK
Python SDK

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('Immediate charge:', preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency);
console.log('New plan details:', preview.new_plan);

preview = client.subscriptions.preview_change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately"
)

# Show customer the charge before confirming
print("Immediate charge:", preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency)
print("New plan details:", preview.new_plan)

Använd preview API för att skapa bekräftelsedialoger som visar kunderna det exakta belopp de kommer att debiteras innan de bekräftar en planändring.

I immediate_charge.summary är customer_credits nett förändringen av kundens kreditsaldo, i den valuta som anges av customer_credits_currency. Detta är valutan för kundens kreditplånbok, vilket är prenumerationens valuta. Den kan skilja sig från sammanfattningens currency, som gäller för total_amount och tax. En kund som till exempel betalar i INR för en prenumeration i USD ser krediter i USD.

Change Plan API

Använd Change Plan API för att ändra produkt, kvantitet och prorateringsbeteende för en aktiv prenumeration.

Snabbstartsexempel

Node.js SDK
Python SDK
Go SDK
HTTP

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function changePlan() {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on) — all null for an ordinary off-session change.
  await client.subscriptions.changePlan('sub_123', {
    product_id: 'pdt_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log('Plan change accepted; awaiting webhooks');
}

changePlan();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

# change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
# client_secret, expires_on) — all None for an ordinary off-session change.
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print("Plan change accepted; awaiting webhooks")

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
  // ChangePlan returns a SubscriptionChangePlanResponse alongside the error.
  _, err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("pdt_new"),
      Quantity:             dodopayments.F(int64(3)),
      ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
      OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
    },
  })
  if err != nil { panic(err) }
  fmt.Println("Plan change applied")
}

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

En lyckad planändring returnerar 200 OK omedelbart — innan någon debitering faktiskt har genomförts. Vad body (ChangePlanResponse) innehåller beror på hur ändringen samlades in:

Fall	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Schemalagd ändring (`effective_at: next_billing_date`)	Alla `null` — inget debiteras ännu
`proration_billing_mode: do_not_bill`	Alla `null` — inget att debitera
Vanlig omedelbar debitering (sparad betalningsmetod)	Alla `null`
`collect_via_payment_link: true` (länk utfärdad)	Alla ifyllda — checkout-referenser för kunden

Detta svar bekräftar att begäran accepterades, inte att en debitering lyckades. För en vanlig omedelbar debitering fastställs resultatet off-session direkt efter anropet. För en begäran med collect_via_payment_link behåller prenumerationen sin aktuella plan tills kunden slutför betalningen.Bekräfta resultatet via webhook (payment.succeeded, payment.failed, subscription.plan_changed) eller genom att läsa prenumerationen igen med GET /subscriptions/{subscription_id} — se Vad händer medan länken är obetald för fallet med betalningslänk.

Om den omedelbara debiteringen misslyckas kan prenumerationen övergå till subscription.on_hold tills betalningen lyckas.

Samla in betalning via en kassalänk

Som standard debiterar en omedelbar planändring prenumerationens sparade betalningsmetod direkt. Ange collect_via_payment_link: true för att i stället skicka kunden till en hostad kassasida — användbart när ingen betalningsmetod har sparats eller när du vill att kunden aktivt ska bekräfta det nya priset.

Detta aktiverar växeln Collect Plan Change Payments by Payment Link i Settings → Subscriptions, som dirigerar Customer Portal:s flöde för planändringar genom checkout.

Krav

collect_via_payment_link: true lyckas endast när alla följande villkor är uppfyllda — annars misslyckas begäran med 422:

Företaget har funktionen allow_plan_change_via_payment_link aktiverad (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at är immediately (standard). En schemalagd ändring (next_billing_date) behöver aldrig en kassasida.
Begäran anger on_payment_failure: prevent_change. Ett uttryckligt apply_change misslyckas med 422.

collect_via_payment_link gäller för alla omedelbara ändringar som leder till en debitering, inklusive nedgraderingar, så länge kraven ovan är uppfyllda.

Om ändringen blir noll eller en kredit utfärdas ingen betalningslänk: payment_link och de andra checkout-fälten returneras som null, och ändringen tillämpas omedelbart. Detta är inte ett 422. Anropa Preview Plan Change först för att kontrollera beloppet innan du begär en länk.

Node.js SDK
Python SDK
HTTP

const response = await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'immediately',
  on_payment_failure: 'prevent_change',
  collect_via_payment_link: true,
});

// Hand response.payment_link to your frontend and send the customer there
console.log(response.payment_link);

response = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    effective_at="immediately",
    on_payment_failure="prevent_change",
    collect_via_payment_link=True,
)

# Hand response.payment_link to your frontend and send the customer there
print(response.payment_link)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "effective_at": "immediately",
    "on_payment_failure": "prevent_change",
    "collect_via_payment_link": true
  }'

En lyckad begäran returnerar checkout-referenserna:

{
  "payment_id": "<payment_id>",
  "payment_link": "https://checkout.dodopayments.com/...",
  "client_secret": "<client_secret>",
  "expires_on": "<expires_on>"
}

Vad händer medan länken är obetald

Prenumerationen stannar på sin aktuella plan — product_id, recurring_pre_tax_amount och next_billing_date förblir oförändrade tills länken har betalats.
En ytterligare begäran med change-plan avvisas med 409 PendingPlanChangeExists medan länken väntar. Skicka den nya begäran med cancel_older_payment_link: true för att ersätta den väntande ändringen. Se Ersätta en väntande betalningslänk.
Försök igen efter en nekad betalning genom att anropa change-plan igen för att få en ny länk.
Om länken aldrig betalas slutar den att fungera efter expires_on — prenumerationen blir automatiskt tillgänglig för en ny begäran om planändring kort därefter.
Om en schemalagd ändring redan fanns och du ersätter den med cancel_scheduled_change_plan: true ligger det ursprungliga schemat kvar medan länken är obetald och avbryts först när länken har betalats — i samma transaktion som tillämpar den nya planen.

När en omedelbar ändring via betalningslänk har utfärdats blockeras alla ytterligare begäranden om planändring för prenumerationen — inklusive den sidoeffektfria förhandsvisningen — tills länken har lösts. En begäran med change-plan kan ersätta länken genom att ange cancel_older_payment_link: true. Förhandsvisningen ignorerar detta fält, så en förhandsvisning förblir blockerad.

Omdirigera kunden efter betalning

Ange return_url för att skicka kunden tillbaka till din webbplats efter att länken har betalats:

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "return_url": "https://example.com/billing/done"
}

Efter checkout går kunden till return_url med följande query-parametrar:

Parameter	Värde
`subscription_id`	Prenumerationen som planändringen gäller.
`payment_id`	Betalningen för planändringen.
`status`	Statusen för betalningen av planändringen, inte prenumerationens status: `active` när den är betald, `failed` när den nekats och `pending` medan den pågår.

När betalningen misslyckas förblir prenumerationen aktiv på sin aktuella plan. Den nya planen kan börja gälla kort efter omdirigeringen, när betalningswebhooken anländer, så läs prenumerationen igen innan du visar den nya planen. return_url kräver collect_via_payment_link: true. Utan detta misslyckas begäran med 422.

Ersätta en väntande betalningslänk

Om kunden lämnar checkout utan att betala anger du cancel_older_payment_link: true i nästa begäran med change-plan. Dodo Payments avbryter den obetalda länken och den nya planändringen ersätter den väntande. Den avbrutna länken accepterar inte längre någon betalning, inte ens på en checkout-sida som redan är öppen.

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "cancel_older_payment_link": true
}

Begäran valideras innan länken avbryts, så en ogiltig begäran lämnar kundens länk intakt. Länken avbryts endast om kunden inte har börjat betala:

Föregående betalning	Svar
Inte öppnad, öppnad men obetald eller nekad	`200` med den nya länken.
Kunden betalar just nu, till exempel under 3D Secure	`409` `PLAN_CHANGE_PAYMENT_IN_PROGRESS`. Försök igen när betalningen har slutförts eller misslyckats.
Redan betald	`409` `PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED`. Försök inte igen: den föregående planändringen tillämpas.
Länken kunde inte avbrytas	`503` `PLAN_CHANGE_LINK_CANCEL_FAILED`. Inget ändrades, så du kan försöka igen.

Varje begäran med change-plan utfärdar en egen faktura. Den ersatta planändringen och dess faktura avbryts. Om ingen planändring väntar har cancel_older_payment_link ingen effekt.

En kontroll som körs efter valideringen, till exempel minimibeloppet för debitering, kan fortfarande misslyckas efter att länken har avbrutits. Prenumerationen stannar då på sin aktuella plan utan någon öppen länk. Skicka begäran igen för att utfärda en ny länk.

Hantera tillägg

När du ändrar prenumerationsplaner kan du även ändra tillägg:

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

Tillägg inkluderas i prorateringsberäkningen och debiteras enligt det valda prorateringsläget.

Tillämpa rabattkoder

Tillämpa en eller flera staplade rabattkoder när du ändrar prenumerationsplaner (max 20, tillämpas i arrayordning):

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

# Apply stacked discount codes during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_codes=["UPGRADE20"]
)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

Rabattbeteende vid planändring

Värdet för `discount_codes`	Beteende
Inte angivet / `null`	Befintliga rabatter med `preserve_on_plan_change=true` bevaras automatiskt om de gäller för den nya produkten.
`[]` (tom array)	Alla befintliga rabatter tas bort från prenumerationen.
`["CODE_A", "CODE_B", ...]`	Ersätter alla befintliga rabatter med denna staplade uppsättning, som valideras och tillämpas i arrayordning.

Det singulära fältet discount_code på denna endpoint är föråldrat, men fungerar fortfarande av bakåtkompatibilitetsskäl — befintliga integrationer behöver inte ändras omedelbart. Det kan inte kombineras med discount_codes i samma begäran. Migrera till arrayformen när det passar.

Använd Preview Plan Change API med discount_codes för att visa kunderna exakt hur mycket de sparar innan de bekräftar planändringen.

Prorateringslägen

Välj hur kunden ska debiteras när planer ändras:

`prorated_immediately`

Krediterar den outnyttjade delen av den aktuella cykeln — basplan, kvantitet och tillägg — proraterat efter återstående tid
Debiterar sedan en hel cykel för den nya planen, kvantiteten och tilläggen. Själva debiteringen prorateras aldrig
Omedelbar nettodebitering = (hel ny cykel) − (återstående andel × hel gammal cykel)
Om krediten överstiger debiteringen för den nya cykeln (vanligt vid nedgraderingar) hålls mellanskillnaden som prenumerationsspecifik kredit för framtida förnyelser
Under en provperiod debiteras kunden omedelbart och byter till den nya planen nu

`full_immediately`

Debiterar hela beloppet för den nya planen omedelbart
Ignorerar återstående tid på den gamla planen — ingen kredit för den aktuella cykeln

Krediter som skapas av prorated_immediately och av nedgraderingar med difference_immediately är prenumerationsspecifika och skiljer sig från förmåner i Credit-Based Billing. De tillämpas automatiskt på framtida förnyelser av samma prenumeration och kan inte överföras mellan prenumerationer.

`difference_immediately`

Uppgradering: debiterar omedelbart prisskillnaden mellan de gamla och nya planerna
Nedgradering: lägger till återstående värde som intern kredit på prenumerationen och tillämpar den automatiskt vid förnyelser

`do_not_bill`

Inga debiteringar eller krediter beräknas
Kunden byter omedelbart till den nya planen utan någon faktureringsjustering
Faktureringscykeln förblir oförändrad
Passar bäst för kostnadsfria migreringar, byte till kostnadsfria planer eller när kostnadsskillnader absorberas

Funktion	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Uppgraderingsdebitering	Hel ny cykel minus kredit för outnyttjad tid	Hela prisskillnaden mellan planerna	Hela priset för den nya planen	Ingen debitering
Nedgraderingskredit	Kredit för outnyttjad tid minus en hel ny cykel	Hela prisskillnaden som kredit	Ingen kredit	Ingen kredit
Faktureringscykel	Återställs till idag	Återställs till idag	Återställs till idag	Oförändrad
Beteende under provperiod	Provperioden avslutas, debiteras omedelbart	Provperioden avslutas, debiteras omedelbart	Provperioden avslutas, hela beloppet debiteras	Slutdatumet för provperioden behålls, ingen debitering
Passar bäst för	Kreditering av outnyttjad tid	Enkel beräkning av uppgradering/nedgradering	Återställning av faktureringscykler	Kostnadsfria migreringar eller byten som goodwill
Komplexitet	Medel (dagsberäkning)	Låg (enkel subtraktion)	Låg (full debitering)	Ingen

Exempelscenarier

Använd dessa standardiserade siffror konsekvent:

Aktuell plan: Basic på $30/månad
Målplan för uppgradering: Pro på $80/månad
Målplan för nedgradering (från Pro): Starter på $20/månad
Faktureringscykel: 30 dagar, startade 1 januari
Planändringen sker 16 januari (15 dagar återstår, 15 dagar har förflutit)

Upgrade: Basic ($30) → Pro ($80) with prorated_immediately

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $80.00 (never prorated)

Step 3: Calculate immediate charge
  Charge = Full new cycle − Credit
  Charge = $80.00 − $15.00 = $65.00

→ Customer pays $65.00 now
→ Customer starts a full month of Pro today
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with prorated_immediately

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $20.00 (never prorated)

Step 3: Net the two
  Net = $20.00 − $40.00 = −$20.00

→ No charge — $20.00 credit added to subscription
→ Billing cycle resets to today (January 16)
→ Credit auto-applies to future renewals
→ Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 (credit exhausted)
→ Following renewal (Mar 15): $20.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_starter',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with difference_immediately

Immediate charge = New plan price − Old plan price
                 = $80 − $30
                 = $50.00

→ Customer pays $50.00 now (regardless of cycle position)
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with difference_immediately

Credit = Old plan price − New plan price
       = $80 − $20
       = $60.00

→ No charge — $60.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal: $20.00 − $20.00 (from credit) = $0.00
→ Following renewal: $20.00 − $20.00 (from credit) = $0.00
→ Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with full_immediately

Immediate charge = Full new plan price = $80.00

→ Customer pays $80.00 now
→ No credit for unused time on old plan
→ Billing cycle resets to today (January 16)
→ Next renewal: February 16 at $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})

Mid-cycle upgrade with add-ons using prorated_immediately

Current: Basic plan ($30/month), no add-ons
New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
Change on day 16 of 30 (15 days remaining)

Step 1: Credit the unused time on the current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan + add-ons
  New plan = $80.00
  Add-ons  = $30.00
  Total new = $110.00 (never prorated)

Step 3: Immediate charge
  Charge = $110.00 − $15.00 = $95.00

→ Customer pays $95.00 now
→ Next renewal: $80.00 + $30.00 = $110.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

Så behandlar varje läge faktureringen

Välj prorated_immediately för att kreditera outnyttjad tid på den gamla planen och samtidigt debitera en hel cykel av den nya; välj full_immediately för att starta om faktureringen; använd difference_immediately för enkla uppgraderingar och automatisk kreditering vid nedgraderingar; eller använd do_not_bill för att byta plan utan någon faktureringsjustering.

Hantera betalningsfel

Styr vad som händer när en betalning för en planändring misslyckas med parametern on_payment_failure.

Lägen för betalningsfel

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Beteende: Behåll prenumerationen på den aktuella planen tills betalningen lyckas.

Planändringen markeras som “pending”
Kunden behåller åtkomsten till sin aktuella plan
Prenumerationen övergår till tillståndet active först efter en lyckad betalning
Användbart när du vill säkerställa betalning innan uppgraderade funktioner beviljas

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

Beteende: Tillämpa planändringen omedelbart oavsett betalningsresultat.

Planändringen tillämpas även om betalningen misslyckas
Kunden får omedelbar åtkomst till den nya planen
Prenumerationen kan övergå till on_hold om betalningen misslyckas
Passar för uppgraderingar som inte är kritiska eller när du litar på kunden

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'apply_change' // This is the default
});

Om inget anges använder parametern on_payment_failure den standardinställning på företagsnivå som konfigurerats i dashboarden.

När varje läge ska användas

Scenario	Rekommenderat läge	Orsak
Uppgradering till premiumfunktioner	`prevent_change`	Säkerställ betalning innan åtkomst beviljas
Ökad kvantitet (fler platser)	`prevent_change`	Förhindra användning utan betalning
Nedgradering av planer	`apply_change`	Kunden minskar sina utgifter
Betrodda företagskunder	`apply_change`	Lägre risk för utebliven betalning
Konvertering från provperiod till betalning	`prevent_change`	Kritisk betalningstidpunkt

Företags- och insamlingsstandarder

Ange standardbeteende för uppgraderingar och nedgraderingar på företagsnivå under Settings → Subscriptions. Dessa standardvärden gäller för alla planändringar i kundportalen och kan åsidosättas per produktsamling. Separata standardvärden finns för uppgraderingar och nedgraderingar:

Inställning	Fält (uppgradering / nedgradering)	Standard (uppgradering)	Standard (nedgradering)
När den nya planen börjar	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
Hur kunden debiteras	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Om kundens betalning misslyckas	`on_payment_failure`	`apply_change`	`apply_change`

Konfigurera företagsstandarder under Settings → Subscriptions och åsidosättningar för samlingar i varje produktsamling. Varje samlingsfält är oberoende — lämna det tomt för att ärva företagets standardvärde eller ange ett värde för att åsidosätta det.

Prioritetsordning

För en viss planändring löses varje inställning i följande ordning:

per-request value (Change Plan API) → collection field (if set) → business field → system default

Ett värde som uttryckligen skickas till Change Plan API gäller alltid. Företags- och samlingsstandarder används endast när inget uttryckligt värde anges — vilket gäller för alla planändringar som initieras från kundportalen.

En vanlig konfiguration är att behålla uppgraderingar på immediately + difference_immediately så att kunderna betalar skillnaden och får åtkomst direkt, och att behålla nedgraderingar på next_billing_date så att kunderna behåller sin aktuella plan tills cykeln är slut.

Hantera webhooks

Följ prenumerationens tillstånd via webhooks för att bekräfta planändringar och betalningar.

Händelsetyper att hantera

subscription.active: prenumerationen aktiverad
subscription.plan_changed: prenumerationsplanen ändrad (uppgradering/nedgradering/ändringar av tillägg)
subscription.on_hold: debiteringen misslyckades, förnyelser stoppade
subscription.renewed: förnyelsen lyckades
payment.succeeded: betalningen för planändringen eller förnyelsen lyckades
payment.failed: betalningen misslyckades

Basera affärslogiken på prenumerationshändelser och använd betalningshändelser för bekräftelse och avstämning.

Verifiera signaturer och hantera avsikter

Next.js Route Handler
Express.js

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req) {
  const webhookId = req.headers.get('webhook-id');
  const webhookSignature = req.headers.get('webhook-signature');
  const webhookTimestamp = req.headers.get('webhook-timestamp');
  const secret = process.env.DODO_PAYMENTS_WEBHOOK_KEY;

  const payload = await req.text();
  // verifySignature is a placeholder – in production, use a Standard Webhooks library
  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

  switch (event.type) {
    case 'subscription.active':
      // mark subscription active in your DB
      break;
    case 'subscription.plan_changed':
      // refresh entitlements and reflect the new plan in your UI
      break;
    case 'subscription.on_hold':
      // notify user to update payment method
      break;
    case 'subscription.renewed':
      // extend access window
      break;
    case 'payment.succeeded':
      // reconcile payment for plan change
      break;
    case 'payment.failed':
      // log and alert
      break;
    default:
      // ignore unknown events
      break;
  }

  return NextResponse.json({ received: true });
}

import express from 'express';

const app = express();
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const webhookId = req.header('webhook-id');
  const webhookSignature = req.header('webhook-signature');
  const webhookTimestamp = req.header('webhook-timestamp');
  const secret = process.env.DODO_PAYMENTS_WEBHOOK_KEY;
  const payload = req.body.toString('utf8');

  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return res.status(400).send('Invalid signature');

  // handle events like above
  res.json({ received: true });
});

app.listen(3000);

För detaljerade payload-scheman, se payloads för prenumerationswebhooks och payloads för betalningswebhooks.

Bästa praxis

Strategi för planändringar

Testa noggrant: Testa alltid planändringar i testläge före produktion
Välj proratering med omsorg: Välj det prorateringsläge som passar din affärsmodell
Hantera fel på ett robust sätt: Implementera korrekt felhantering och logik för nya försök
Övervaka lyckade ändringar: Följ hur ofta planändringar lyckas eller misslyckas och undersök problem

Webhook-implementation

Verifiera signaturer: Validera alltid webhook-signaturer för att säkerställa äkthet
Implementera idempotens: Hantera duplicerade webhook-händelser på ett robust sätt
Bearbeta asynkront: Blockera inte webhook-svar med tunga operationer
Logga allt: För detaljerade loggar för felsökning och granskningsändamål

Användarupplevelse

Kommunicera tydligt: Informera kunderna om faktureringsändringar och tidpunkter
Ge bekräftelser: Skicka bekräftelsemejl för lyckade planändringar
Hantera specialfall: Ta hänsyn till provperioder, proratering och misslyckade betalningar
Uppdatera gränssnittet omedelbart: Återspegla planändringar i applikationens gränssnitt

Vanliga problem och lösningar

Lös typiska problem som uppstår vid ändringar av prenumerationsplaner:

Charge created but subscription not updated

Symptom: API-anropet lyckas men prenumerationen ligger kvar på den gamla planenVanliga orsaker:

Webhook-bearbetningen misslyckades eller fördröjdes
Applikationens tillstånd uppdaterades inte efter mottagna webhooks
Problem med databastransaktioner under tillståndsuppdateringen

Lösningar:

Implementera webhook-hantering med logik för nya försök
Använd idempotenta operationer för tillståndsuppdateringar
Lägg till övervakning för att upptäcka och avisera om missade webhook-händelser
Kontrollera att webhook-endpointen är åtkomlig och svarar korrekt

Credits not applied after downgrade

Symptom: Kunden nedgraderar men ser inget kreditsaldoVanliga orsaker:

Förväntningar på prorateringsläget: nedgraderingar krediterar hela prisskillnaden mellan planerna med difference_immediately, medan prorated_immediately krediterar den outnyttjade tiden i den gamla cykeln och sedan debiterar en hel cykel för den nya planen — ett kreditsaldo blir därför bara kvar när krediten överstiger priset för den nya planen
Krediter är prenumerationsspecifika och överförs inte mellan prenumerationer
Kreditsaldot visas inte i kundpanelen

Lösningar:

Använd difference_immediately för nedgraderingar när du vill ha automatiska krediter
Förklara för kunderna att krediter tillämpas på framtida förnyelser av samma prenumeration
Implementera kundportalen så att kreditsaldon visas
Kontrollera nästa fakturaförhandsvisning för att se tillämpade krediter

Webhook signature verification fails

Symptom: Webhook-händelser avvisas på grund av ogiltig signaturVanliga orsaker:

Felaktig webhook-hemlighet
Rå request body ändrades före signaturverifieringen
Fel algoritm för signaturverifiering

Lösningar:

Kontrollera att du använder korrekt DODO_PAYMENTS_WEBHOOK_KEY från dashboarden
Läs den råa request body innan någon JSON-parsning sker
Använd standardbiblioteket för webhook-verifiering för din plattform
Testa webhook-signaturverifieringen i utvecklingsmiljön

Plan change fails with 422 error

Symptom: API returnerar felet 422 Unprocessable EntityVanliga orsaker:

Ogiltigt prenumerations-ID eller produkt-ID
Prenumerationen är inte i aktivt tillstånd
Obligatoriska parametrar saknas
Produkten är inte tillgänglig för planändringar

Lösningar:

Kontrollera att prenumerationen finns och är aktiv
Kontrollera att produkt-ID:t är giltigt och tillgängligt
Säkerställ att alla obligatoriska parametrar anges
Läs API-dokumentationen för parameterkrav

Immediate charge fails during plan change

Symptom: Planändringen initierades men den omedelbara debiteringen misslyckasVanliga orsaker:

Otillräckliga medel på kundens betalningsmetod
Betalningsmetoden har löpt ut eller är ogiltig
Banken nekade transaktionen
Bedrägeridetektering blockerade debiteringen

Lösningar:

Hantera webhook-händelser med payment.failed på lämpligt sätt
Meddela kunden att betalningsmetoden behöver uppdateras
Implementera logik för nya försök vid tillfälliga fel
Överväg att tillåta planändringar när omedelbara debiteringar misslyckas

Subscription on hold after plan change

Symptom: Debiteringen för planändringen misslyckas och prenumerationen övergår till tillståndet on_holdVad händer: När en debitering för en planändring misslyckas placeras prenumerationen automatiskt i tillståndet on_hold. Prenumerationen förnyas inte automatiskt förrän betalningsmetoden har uppdaterats.Lösning: Uppdatera betalningsmetoden för att återaktivera prenumerationenSå här återaktiverar du en prenumeration från tillståndet on_hold efter en misslyckad planändring:

Uppdatera betalningsmetoden med Update Payment Method API
Automatisk skapelse av debitering: API:t skapar automatiskt en debitering för återstående skulder
Fakturagenerering: En faktura genereras för debiteringen
Betalningshantering: Betalningen behandlas med den nya betalningsmetoden
Återaktivering: När betalningen lyckas återaktiveras prenumerationen till tillståndet active

// Reactivate subscription from on_hold after failed plan change
async function reactivateAfterFailedPlanChange(subscriptionId) {
  // Update payment method - automatically creates charge for remaining dues
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    payment_method: { type: 'new', return_url: 'https://example.com/return' }
  });
  
  if (response.payment_id) {
    console.log('Charge created for remaining dues:', response.payment_id);
    console.log('Payment link:', response.payment_link);
    
    // Redirect customer to payment_link to complete payment
    // Monitor webhooks for:
    // 1. payment.succeeded - charge succeeded
    // 2. subscription.active - subscription reactivated
  }
  
  return response;
}

// Or use existing payment method if available
async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    payment_method: { type: 'existing', payment_method_id: paymentMethodId }
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

# Reactivate subscription from on_hold after failed plan change
def reactivate_after_failed_plan_change(subscription_id):
    # Update payment method - automatically creates charge for remaining dues
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "new", "return_url": "https://example.com/return"},
    )
    
    if response.payment_id:
        print("Charge created for remaining dues:", response.payment_id)
        print("Payment link:", response.payment_link)
        
        # Redirect customer to payment_link to complete payment
        # Monitor webhooks for:
        # 1. payment.succeeded - charge succeeded
        # 2. subscription.active - subscription reactivated
    
    return response

# Or use existing payment method if available
def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "existing", "payment_method_id": payment_method_id},
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

Webhook-händelser att övervaka:

subscription.on_hold: Prenumerationen sattes på paus (mottas när debiteringen för planändringen misslyckas)
payment.succeeded: Betalningen för återstående skulder lyckades (efter uppdatering av betalningsmetoden)
subscription.active: Prenumerationen återaktiverades efter lyckad betalning

Bästa praxis:

Meddela kunderna omedelbart när en debitering för en planändring misslyckas
Ge tydliga instruktioner om hur betalningsmetoden uppdateras
Övervaka webhook-händelser för att följa återaktiveringsstatus
Överväg att implementera automatisk logik för nya försök vid tillfälliga betalningsfel

Update Payment Method API Reference

Visa den fullständiga API-dokumentationen för uppdatering av betalningsmetoder och återaktivering av prenumerationer.

Testa din implementation

Testa din implementation av planändringar för prenumerationer noggrant:

Set up test environment

Använd test-API-nycklar och testprodukter
Skapa testprenumerationer med olika plantyper
Konfigurera en test-endpoint för webhooks
Konfigurera övervakning och loggning

Test different proration modes

Testa prorated_immediately med olika positioner i faktureringscykeln
Testa difference_immediately för uppgraderingar och nedgraderingar
Testa full_immediately för att återställa faktureringscykler
Testa do_not_bill för planbyten utan debitering eller kredit
Kontrollera att krediterna beräknas korrekt

Test webhook handling

Kontrollera att alla relevanta webhook-händelser tas emot
Testa webhook-signaturverifieringen
Hantera duplicerade webhook-händelser på ett robust sätt
Testa scenarier där webhook-bearbetningen misslyckas

Test error scenarios

Testa med ogiltiga prenumerations-ID:n
Testa med utgångna betalningsmetoder
Testa nätverksfel och tidsgränser
Testa med otillräckliga medel

Monitor in production

Konfigurera aviseringar för misslyckade planändringar
Övervaka webhook-bearbetningstider
Följ hur ofta planändringar lyckas
Granska kundsupportärenden om problem med planändringar

Felhantering

Hantera vanliga API-fel på ett robust sätt i din implementation:

HTTP-statuskoder

200 OK

Begäran om planändring behandlades korrekt. Svarskroppen är en ChangePlanResponse med payment_id, payment_link, client_secret och expires_on. Alla fyra kan vara null, så kroppen serialiseras som {} för en vanlig off-session-ändring; de är ifyllda för en lyckad begäran med collect_via_payment_link, som returnerar checkout-referenser — se Samla in betalning via en kassalänk. Om on_payment_failure=prevent_change förblir planändringen väntande tills betalningen lyckas.

400 Bad Request

Ogiltiga parametrar i begäran. Kontrollera att alla obligatoriska fält har angetts och formaterats korrekt.

401 Unauthorized

Ogiltig eller saknad API-nyckel. Kontrollera att din DODO_PAYMENTS_API_KEY är korrekt och har rätt behörigheter.

409 Conflict

En väntande planändring finns redan för denna prenumeration (PendingPlanChangeExists). För en schemalagd ändring avbryter du den med DELETE /subscriptions/{subscription_id}/change-plan/scheduled innan du skickar en ny. För en väntande ändring via betalningslänk skickar du den nya begäran med cancel_older_payment_link: true för att ersätta den. Se Ersätta en väntande betalningslänk.Med cancel_older_payment_link: true betyder 409 att kunden betalar den föregående länken just nu (PLAN_CHANGE_PAYMENT_IN_PROGRESS) eller redan har betalat den (PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED).

503 Service Unavailable

Med cancel_older_payment_link: true kunde den föregående betalningslänken inte avbrytas (PLAN_CHANGE_LINK_CANCEL_FAILED). Inget ändrades, så du kan försöka igen.

422 Unprocessable Entity

Prenumerationen är inaktiv eller on-demand, eller så är begäran inte berättigad till collect_via_payment_link — företaget har inte funktionen aktiverad, effective_at är inte immediately eller on_payment_failure är inte prevent_change. Se Krav. Ett prenumerations-ID som inte finns eller inte tillhör ditt konto returnerar 404 med koden NOT_FOUND.

500 Internal Server Error

Ett serverfel inträffade. Försök igen efter en kort fördröjning.

Format för felsvar

Fel returnerar en JSON-kropp med en code och en läsbar message:

{
  "code": "INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED",
  "message": "Changing plans is not supported for inactive subscriptions"
}

Se Felkoder för hela listan.

Nästa steg

Läs igenom Change Plan API
Utforska Credit-Based Billing
Implementera aviseringar för subscription.on_hold
Läs guiden för webhook-integration

Change Plan API

Plan Change Preview

Integration Guide

​Vad är en uppgradering eller nedgradering av en prenumeration?

​När ska planändringar användas?

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Förhandsvisa planändringar

​Change Plan API

​Snabbstartsexempel

​Samla in betalning via en kassalänk

​Krav

​Vad händer medan länken är obetald

​Omdirigera kunden efter betalning

​Ersätta en väntande betalningslänk

​Hantera tillägg

​Tillämpa rabattkoder

​Rabattbeteende vid planändring

​Prorateringslägen

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Exempelscenarier

​Så behandlar varje läge faktureringen

​Hantera betalningsfel

​Lägen för betalningsfel

​När varje läge ska användas

​Företags- och insamlingsstandarder

​Prioritetsordning

​Hantera webhooks

​Händelsetyper att hantera

​Verifiera signaturer och hantera avsikter

​Bästa praxis

​Strategi för planändringar

​Webhook-implementation

​Användarupplevelse

​Vanliga problem och lösningar

Update Payment Method API Reference

​Testa din implementation

​Felhantering

​HTTP-statuskoder

​Format för felsvar

​Nästa steg

Vad är en uppgradering eller nedgradering av en prenumeration?

När ska planändringar användas?

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Förhandsvisa planändringar

Change Plan API

Snabbstartsexempel

Samla in betalning via en kassalänk

Krav

Vad händer medan länken är obetald

Omdirigera kunden efter betalning

Ersätta en väntande betalningslänk

Hantera tillägg

Tillämpa rabattkoder

Rabattbeteende vid planändring

Prorateringslägen

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Exempelscenarier

Så behandlar varje läge faktureringen

Hantera betalningsfel

Lägen för betalningsfel

När varje läge ska användas

Företags- och insamlingsstandarder

Prioritetsordning

Hantera webhooks

Händelsetyper att hantera

Verifiera signaturer och hantera avsikter

Bästa praxis

Strategi för planändringar

Webhook-implementation

Användarupplevelse

Vanliga problem och lösningar

Testa din implementation

Felhantering

HTTP-statuskoder

Format för felsvar

Nästa steg