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.

Apa Itu Upgrade atau Downgrade Subscription?

Ubah plan subscription pelanggan untuk memindahkan mereka antar-tier, menyesuaikan quantity untuk produk berbasis seat, atau memigrasikan mereka ke produk baru. API secara otomatis menghitung prorasi dan biaya berdasarkan billing mode yang Anda pilih.

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

Kapan Menggunakan Perubahan Plan

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

Untuk petunjuk penyiapan terperinci, lihat Integration Guide.

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

Cocok untuk: Aplikasi SaaS yang ingin memberikan kredit untuk waktu yang tidak terpakai pada plan lama.

Mengkreditkan bagian yang tidak terpakai dari siklus saat ini, diprorata berdasarkan waktu yang tersisa
Kemudian menagih satu siklus penuh pada plan baru — harga plan baru tidak pernah diprorata
Biaya bersih = siklus baru penuh − (fraksi yang tersisa × siklus lama penuh)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

wajib

The ID of the active subscription to modify.

string

wajib

The new product ID to change the subscription to.

integer

wajib

Jumlah unit untuk rencana baru (untuk produk berbasis kursi).

string

wajib

How to handle immediate billing: prorated_immediately, full_immediately, difference_immediately, or do_not_bill.

array

Add-on opsional untuk paket baru. Menghilangkan field ini, mengirim null, atau mengirim array kosong akan menghapus add-on yang sudah ada, jadi sertakan add-on saat ini untuk mempertahankannya.

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.

boolean

Kumpulkan jumlah perubahan paket melalui tautan pembayaran, bukan dengan menagih metode pembayaran tersimpan milik subscription. Customer membayar di halaman checkout yang di-host.Memerlukan capability allow_plan_change_via_payment_link milik bisnis (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately, dan on_payment_failure: prevent_change. Lihat Collecting Payment via a Checkout Link. Diabaikan oleh preview route.

array

Kode diskon stacked opsional yang akan diterapkan pada plan baru (maks. 20, diterapkan sesuai urutan dalam array). Perilakunya bergantung pada nilai yang Anda kirim:

Tidak diberikan / null — diskon yang ada dengan preserve_on_plan_change=true dipertahankan jika berlaku untuk produk baru.
[] (array kosong) — menghapus semua diskon yang ada dari subscription.
["CODE_A", "CODE_B", ...] — mengganti semua diskon yang ada dengan kumpulan stacked ini.

string

usang

Deprecated — gunakan discount_codes untuk integration baru. Field ini masih berfungsi untuk backward compatibility, tetapi tidak dapat digabungkan dengan discount_codes dalam request yang sama.

string

default:"immediately"

Kapan perubahan plan diterapkan:

immediately (default): Terapkan perubahan plan segera
next_billing_date: Jadwalkan perubahan pada tanggal billing berikutnya. Pelanggan tetap menggunakan plan saat ini hingga periode billing berakhir. Gunakan opsi ini untuk downgrade agar pelanggan tetap memperoleh manfaat plan saat ini hingga akhir periode billing.

Handle Webhook Events

Siapkan penanganan webhook untuk melacak hasil perubahan plan:

subscription.active: Perubahan plan berhasil, subscription diperbarui
subscription.plan_changed: Plan subscription berubah (upgrade/downgrade/update addon)
subscription.on_hold: Biaya perubahan plan gagal, renewal dihentikan
payment.succeeded: Biaya langsung untuk perubahan plan berhasil
payment.failed: Biaya langsung gagal

Selalu verifikasi signature webhook dan terapkan pemrosesan event yang idempoten.

Update Your Application State

Berdasarkan event webhook, perbarui aplikasi Anda:

Berikan/cabut fitur berdasarkan plan baru
Perbarui dashboard pelanggan dengan detail plan baru
Kirim email konfirmasi tentang perubahan plan
Catat perubahan billing untuk keperluan audit

Test and Monitor

Uji implementasi Anda secara menyeluruh:

Uji semua mode prorasi dengan berbagai skenario
Pastikan penanganan webhook berfungsi dengan benar
Pantau tingkat keberhasilan perubahan plan
Siapkan alert untuk perubahan plan yang gagal

Implementasi perubahan plan subscription Anda kini siap digunakan di production.

Preview Perubahan Plan

Sebelum menerapkan perubahan plan, gunakan Preview API untuk menunjukkan kepada pelanggan jumlah pasti yang akan ditagihkan:

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)

Gunakan preview API untuk membuat dialog konfirmasi yang menampilkan jumlah pasti yang akan ditagihkan kepada pelanggan sebelum mereka mengonfirmasi perubahan plan.

Change Plan API

Gunakan Change Plan API untuk mengubah product, quantity, dan perilaku prorasi pada subscription yang aktif.

Contoh Quick Start

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"
  }'

Perubahan plan yang berhasil mengembalikan 200 OK segera — sebelum biaya apa pun benar-benar diselesaikan. Isi body (ChangePlanResponse) bergantung pada cara perubahan tersebut ditagihkan:

Kasus	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Perubahan terjadwal (`effective_at: next_billing_date`)	Semua `null` — belum ada biaya yang ditagihkan
`proration_billing_mode: do_not_bill`	Semua `null` — tidak ada yang perlu ditagihkan
Biaya langsung biasa (payment method tersimpan)	Semua `null`
`collect_via_payment_link: true` (link diterbitkan)	Semua terisi — checkout handle untuk pelanggan

Response ini mengonfirmasi bahwa request diterima, bukan bahwa biaya berhasil. Untuk biaya langsung biasa, hasilnya diselesaikan secara off-session segera setelah pemanggilan. Untuk request collect_via_payment_link, subscription tetap menggunakan plan saat ini hingga pelanggan menyelesaikan pembayaran.Konfirmasikan hasilnya melalui webhook (payment.succeeded, payment.failed, subscription.plan_changed) atau dengan membaca ulang subscription menggunakan GET /subscriptions/{subscription_id} — lihat What Happens While the Link Is Unpaid untuk kasus payment-link.

Jika biaya langsung gagal, subscription dapat berpindah ke status subscription.on_hold hingga pembayaran berhasil.

Mengumpulkan Pembayaran melalui Checkout Link

Secara default, perubahan plan langsung menagih payment method yang tersimpan pada subscription. Atur collect_via_payment_link: true untuk mengarahkan pelanggan ke halaman checkout yang di-host — berguna jika tidak ada payment method tersimpan atau Anda ingin pelanggan secara aktif mengonfirmasi harga baru.

Ini mengaktifkan toggle Collect Plan Change Payments by Payment Link di Settings → Subscriptions, yang mengarahkan alur perubahan plan Customer Portal melalui checkout.

Requirements

collect_via_payment_link: true hanya berhasil jika semua kondisi berikut terpenuhi — jika tidak, request gagal dengan 422:

Bisnis memiliki capability allow_plan_change_via_payment_link yang diaktifkan (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at adalah immediately (default). Perubahan terjadwal (next_billing_date) tidak pernah memerlukan halaman checkout.
on_payment_failure efektif menghasilkan prevent_change. Anda tidak perlu mengirimkannya secara eksplisit — jika default tingkat bisnis Anda sudah berupa prevent_change, menghilangkan field ini sudah memenuhi kondisi. apply_change eksplisit akan gagal dengan 422.

collect_via_payment_link berlaku untuk setiap perubahan langsung yang menghasilkan biaya, termasuk downgrade, selama requirements di atas terpenuhi.

Jika perubahan menghasilkan nol atau kredit, payment link tidak diterbitkan: payment_link dan field checkout lainnya dikembalikan sebagai null, dan perubahan langsung diterapkan. Ini bukan 422. Panggil Preview Plan Change terlebih dahulu untuk memeriksa jumlahnya sebelum meminta link.

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
  }'

Request yang berhasil mengembalikan checkout handle:

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

Apa yang Terjadi Saat Link Belum Dibayar

Subscription tetap menggunakan plan saat ini — product_id, recurring_pre_tax_amount, dan next_billing_date semuanya tidak berubah hingga link dibayar.
Request change-plan berikutnya ditolak dengan 409 PendingPlanChangeExists saat link masih tertunda. Batalkan perubahan terjadwal dengan DELETE /subscriptions/{subscription_id}/change-plan/scheduled jika diperlukan, tetapi endpoint tersebut tidak membatalkan perubahan payment-link yang tertunda — hanya pembayaran berhasil atau kedaluwarsa yang dapat melakukannya.
Pelanggan dapat mencoba kembali kartu pada checkout session yang sama setelah penolakan; pemanggilan change-plan baru bukan cara untuk mencoba kembali.
Jika link tidak pernah dibayar, link berhenti berfungsi setelah expires_on — subscription secara otomatis dapat menerima request perubahan plan baru tidak lama kemudian.
Jika perubahan terjadwal sudah ada dan Anda menggantinya dengan cancel_scheduled_change_plan: true, jadwal asli tetap berlaku saat link belum dibayar dan hanya dibatalkan setelah link dibayar — dalam transaksi yang sama ketika plan baru diterapkan.

Setelah perubahan payment-link langsung diterbitkan, setiap request perubahan plan berikutnya pada subscription tersebut — termasuk preview tanpa side effect — diblokir hingga link selesai diproses. Jangan menerbitkan link yang tidak Anda inginkan untuk segera dibayar pelanggan.

Mengelola Addon

Saat mengubah plan subscription, Anda juga dapat mengubah addon:

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

Addon disertakan dalam penghitungan prorasi dan akan ditagihkan sesuai mode prorasi yang dipilih.

Menerapkan Kode Diskon

Terapkan satu atau beberapa kode diskon stacked saat mengubah plan subscription (maks. 20, diterapkan sesuai urutan dalam array):

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"]
  }'

Perilaku Diskon saat Perubahan Plan

Nilai `discount_codes`	Perilaku
Tidak diberikan / `null`	Diskon yang ada dengan `preserve_on_plan_change=true` otomatis dipertahankan jika berlaku untuk produk baru.
`[]` (array kosong)	Semua diskon yang ada dihapus dari subscription.
`["CODE_A", "CODE_B", ...]`	Mengganti semua diskon yang ada dengan kumpulan stacked ini, yang divalidasi dan diterapkan sesuai urutan dalam array.

Field tunggal discount_code pada endpoint ini deprecated, tetapi masih berfungsi untuk backward compatibility — integration yang sudah ada tidak perlu segera diubah. Field ini tidak dapat digabungkan dengan discount_codes dalam request yang sama. Migrasikan ke bentuk array saat memungkinkan.

Gunakan Preview Plan Change API dengan discount_codes untuk menunjukkan kepada pelanggan jumlah yang dapat mereka hemat sebelum mengonfirmasi perubahan plan.

Mode Prorasi

Pilih cara menagih pelanggan saat mengubah plan:

`prorated_immediately`

Mengkreditkan bagian yang tidak terpakai dari siklus saat ini — base plan, quantity, dan addon — diprorata berdasarkan waktu yang tersisa
Kemudian menagih satu siklus penuh pada plan, quantity, dan addon baru. Biaya itu sendiri tidak pernah diprorata
Biaya langsung bersih = (siklus baru penuh) − (fraksi yang tersisa × siklus lama penuh)
Jika kredit melebihi biaya siklus baru (umum terjadi pada downgrade), selisihnya disimpan sebagai kredit pada subscription untuk renewal mendatang
Jika sedang dalam trial, langsung menagih dan beralih ke plan baru sekarang

`full_immediately`

Menagih jumlah penuh plan baru secara langsung
Mengabaikan waktu yang tersisa dari plan lama — tidak ada kredit untuk siklus saat ini

Kredit yang dibuat oleh prorated_immediately dan oleh downgrade menggunakan difference_immediately memiliki cakupan subscription dan berbeda dari entitlement Credit-Based Billing. Kredit tersebut otomatis diterapkan pada renewal mendatang dari subscription yang sama dan tidak dapat dipindahkan antar-subscription.

`difference_immediately`

Upgrade: langsung menagih selisih harga antara plan lama dan baru
Downgrade: menambahkan nilai yang tersisa sebagai kredit internal ke subscription dan menerapkannya secara otomatis pada renewal

`do_not_bill`

Tidak ada biaya atau kredit yang dihitung
Pelanggan langsung beralih ke plan baru tanpa penyesuaian billing
Siklus billing tetap tidak berubah
Cocok untuk migrasi sebagai bentuk penghargaan, perpindahan ke plan gratis, atau menyerap perbedaan biaya

Fitur	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Biaya upgrade	Siklus baru penuh, dikurangi kredit untuk waktu yang tidak terpakai	Selisih harga penuh antar-plan	Harga penuh plan baru	Tidak ada biaya
Kredit downgrade	Kredit untuk waktu yang tidak terpakai, dikurangi satu siklus baru penuh	Selisih harga penuh sebagai kredit	Tidak ada kredit	Tidak ada kredit
Siklus billing	Diatur ulang ke hari ini	Diatur ulang ke hari ini	Diatur ulang ke hari ini	Tidak berubah
Perilaku trial	Trial berakhir, langsung ditagih	Trial berakhir, langsung ditagih	Trial berakhir, ditagih jumlah penuh	Tanggal akhir trial tetap, tidak ada biaya
Cocok untuk	Mengkreditkan waktu yang tidak terpakai	Perhitungan upgrade/downgrade sederhana	Mengatur ulang siklus billing	Migrasi gratis atau perpindahan sebagai bentuk penghargaan
Kompleksitas	Sedang (perhitungan hari)	Rendah (pengurangan sederhana)	Rendah (biaya penuh)	Tidak ada

Kredit yang dibuat oleh prorated_immediately dan oleh downgrade menggunakan difference_immediately memiliki cakupan subscription dan berbeda dari entitlement Credit-Based Billing. Kredit tersebut otomatis diterapkan pada renewal mendatang untuk subscription yang sama dan tidak dapat ditransfer antar-subscription.

`difference_immediately`

Upgrade: segera menagih selisih harga antara paket lama dan baru
Downgrade: menambahkan nilai tersisa sebagai kredit internal ke subscription dan menerapkannya otomatis pada renewal

`do_not_bill`

Tidak ada penagihan atau kredit yang dihitung
Customer segera beralih ke paket baru tanpa penyesuaian billing
Siklus billing tetap tidak berubah
Cocok untuk migrasi sebagai bentuk goodwill, perpindahan ke paket gratis, atau penyerapan perbedaan biaya

Fitur	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Tagihan upgrade	Siklus baru penuh, dikurangi kredit untuk waktu yang tidak terpakai	Selisih harga penuh antara paket	Harga paket baru penuh	Tidak ada tagihan
Kredit downgrade	Kredit untuk waktu yang tidak terpakai, dikurangi siklus baru penuh	Selisih harga penuh sebagai kredit	Tidak ada kredit	Tidak ada kredit
Siklus penagihan	Diatur ulang ke hari ini	Diatur ulang ke hari ini	Diatur ulang ke hari ini	Tidak berubah
Perilaku trial	Mengakhiri trial, langsung menagihkan	Mengakhiri trial, langsung menagihkan	Mengakhiri trial, menagihkan jumlah penuh	Mengakhiri trial, tanpa tagihan
Cocok untuk	Mengkreditkan waktu yang tidak terpakai	Perhitungan upgrade/downgrade sederhana	Mengatur ulang siklus penagihan	Migrasi gratis atau perpindahan sebagai bentuk courtesy
Kompleksitas	Sedang (perhitungan hari)	Rendah (pengurangan sederhana)	Rendah (tagihan penuh)	Tidak ada

Skenario contoh

Gunakan angka kanonis berikut secara konsisten:

Paket saat ini: Basic seharga $30/bulan
Target upgrade: Pro seharga $80/bulan
Target downgrade (dari Pro): Starter seharga $20/bulan
Siklus billing: 30 hari, dimulai pada January 1
Perubahan paket terjadi pada January 16 (tersisa 15 hari, 15 hari telah digunakan)

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 }
  ]
})

Cara setiap mode memproses billing

Pilih prorated_immediately untuk mengkreditkan waktu yang tidak terpakai pada paket lama sekaligus menagihkan siklus penuh pada paket baru; pilih full_immediately untuk memulai ulang penagihan; gunakan difference_immediately untuk upgrade sederhana dan kredit otomatis saat downgrade; atau gunakan do_not_bill untuk beralih paket tanpa penyesuaian penagihan apa pun.

Menangani Kegagalan Pembayaran

Kontrol apa yang terjadi ketika pembayaran perubahan paket gagal menggunakan parameter on_payment_failure.

Mode Kegagalan Pembayaran

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Perilaku: Pertahankan subscription pada paket saat ini hingga pembayaran berhasil.

Perubahan paket ditandai sebagai “pending”
Customer tetap memiliki akses ke paket saat ini
Subscription berpindah ke status active hanya setelah pembayaran berhasil
Berguna ketika Anda ingin memastikan pembayaran sebelum memberikan fitur yang ditingkatkan

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

Perilaku: Terapkan perubahan paket segera, apa pun hasil pembayarannya.

Perubahan paket diterapkan meskipun pembayaran gagal
Customer langsung memperoleh akses ke paket baru
Subscription dapat berpindah ke status on_hold jika pembayaran gagal
Cocok untuk upgrade yang tidak kritis atau ketika Anda mempercayai customer

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

Jika tidak ditentukan, parameter on_payment_failure menggunakan pengaturan default tingkat business yang dikonfigurasi di dashboard.

Kapan Menggunakan Setiap Mode

Skenario	Mode yang Direkomendasikan	Alasan
Upgrade ke fitur premium	`prevent_change`	Pastikan pembayaran sebelum memberikan akses
Penambahan kuantitas (lebih banyak seat)	`prevent_change`	Cegah penggunaan tanpa pembayaran
Downgrade paket	`apply_change`	Customer mengurangi pengeluaran
Customer enterprise tepercaya	`apply_change`	Risiko tidak membayar lebih rendah
Konversi trial ke berbayar	`prevent_change`	Momen pembayaran yang kritis

Default Business & Collection

Daripada mengirim parameter proration pada setiap perubahan paket, Anda dapat menetapkan perilaku default upgrade & downgrade sekali di tingkat business. Default ini berlaku untuk semua perubahan paket melalui customer portal dan dapat ditimpa pada setiap product collection. Terdapat default terpisah untuk upgrade dan downgrade:

Pengaturan	Field (upgrade / downgrade)	Default (upgrade)	Default (downgrade)
Kapan paket baru dimulai	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
Cara customer ditagih	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Jika pembayaran customer gagal	`on_payment_failure`	`apply_change`	`apply_change`

Konfigurasikan default business di Settings → Subscriptions, dan override collection pada setiap product collection. Setiap field collection bersifat independen — biarkan tidak diatur untuk mewarisi dari default business, atau tetapkan nilai untuk menimpanya hanya pada collection tersebut.

Urutan resolusi

Untuk perubahan paket apa pun, setiap pengaturan di-resolve dalam urutan berikut:

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

Nilai yang dikirim secara eksplisit ke Change Plan API selalu menjadi prioritas. Default business dan collection hanya berlaku jika tidak ada nilai eksplisit yang diberikan — seperti pada semua perubahan paket yang dimulai dari customer portal.

Konfigurasi umum: pertahankan upgrade pada immediately + difference_immediately agar customer membayar selisih dan langsung memperoleh akses, serta pertahankan downgrade pada next_billing_date agar customer tetap menggunakan paket saat ini hingga siklus berakhir.

Menangani webhook

Lacak status subscription melalui webhook untuk mengonfirmasi perubahan paket dan pembayaran.

Jenis event yang perlu ditangani

subscription.active: subscription diaktifkan
subscription.plan_changed: paket subscription diubah (upgrade/downgrade/perubahan addon)
subscription.on_hold: penagihan gagal, renewal dihentikan
subscription.renewed: renewal berhasil
payment.succeeded: pembayaran untuk perubahan paket atau renewal berhasil
payment.failed: pembayaran gagal

Kami menyarankan agar logika bisnis didorong oleh event subscription, dan event pembayaran digunakan untuk konfirmasi serta rekonsiliasi.

Memverifikasi signature dan menangani intent

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_WEBHOOK_SECRET;

  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_WEBHOOK_SECRET;
  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);

Untuk schema payload terperinci, lihat Subscription webhook payloads dan Payment webhook payloads.

Praktik Terbaik

Ikuti rekomendasi berikut untuk perubahan paket subscription yang andal:

Strategi Perubahan Paket

Uji secara menyeluruh: Selalu uji perubahan paket dalam test mode sebelum production
Pilih proration dengan cermat: Pilih mode proration yang sesuai dengan model bisnis Anda
Tangani kegagalan dengan baik: Terapkan penanganan error dan logika retry yang tepat
Pantau tingkat keberhasilan: Lacak tingkat keberhasilan/kegagalan perubahan paket dan selidiki masalah

Implementasi Webhook

Verifikasi signature: Selalu validasi signature webhook untuk memastikan keaslian
Terapkan idempotensi: Tangani event webhook duplikat dengan baik
Proses secara asynchronous: Jangan menghambat response webhook dengan operasi berat
Catat semuanya: Simpan log terperinci untuk debugging dan audit

User Experience

Berkomunikasi dengan jelas: Beri tahu customer tentang perubahan dan waktu billing
Berikan konfirmasi: Kirim konfirmasi email untuk perubahan paket yang berhasil
Tangani kasus khusus: Pertimbangkan periode trial, proration, dan pembayaran yang gagal
Perbarui UI segera: Tampilkan perubahan paket pada antarmuka aplikasi Anda

Masalah Umum dan Solusi

Atasi masalah umum yang ditemui selama perubahan paket subscription:

Charge created but subscription not updated

Gejala: Pemanggilan API berhasil, tetapi subscription tetap menggunakan paket lamaPenyebab umum:

Pemrosesan webhook gagal atau tertunda
State aplikasi tidak diperbarui setelah menerima webhook
Masalah transaksi database saat memperbarui state

Solusi:

Terapkan penanganan webhook yang kuat dengan logika retry
Gunakan operasi idempoten untuk pembaruan state
Tambahkan monitoring untuk mendeteksi dan memberi alert atas event webhook yang terlewat
Pastikan endpoint webhook dapat diakses dan merespons dengan benar

Credits not applied after downgrade

Gejala: Customer melakukan downgrade tetapi tidak melihat saldo kreditPenyebab umum:

Ekspektasi mode proration: downgrade mengkreditkan selisih harga penuh paket dengan difference_immediately, sedangkan prorated_immediately mengkreditkan waktu yang tidak terpakai pada siklus lama lalu menagihkan siklus penuh pada paket baru — sehingga saldo kredit hanya tersisa ketika kredit tersebut melebihi harga paket baru
Kredit bersifat spesifik untuk subscription dan tidak dapat ditransfer antar-subscription
Saldo kredit tidak terlihat di dashboard pelanggan

Solusi:

Gunakan difference_immediately untuk downgrade jika Anda menginginkan kredit otomatis
Jelaskan kepada customer bahwa kredit berlaku untuk renewal mendatang pada subscription yang sama
Implementasikan customer portal untuk menampilkan saldo kredit
Periksa preview invoice berikutnya untuk melihat kredit yang diterapkan

Webhook signature verification fails

Gejala: Event webhook ditolak karena signature tidak validPenyebab umum:

Secret key webhook salah
Raw request body diubah sebelum verifikasi signature
Algoritma verifikasi signature salah

Solusi:

Pastikan Anda menggunakan DODO_WEBHOOK_SECRET yang benar dari dashboard
Baca raw request body sebelum middleware parsing JSON apa pun
Gunakan library verifikasi webhook standar untuk platform Anda
Uji verifikasi signature webhook di environment development

Plan change fails with 422 error

Gejala: API mengembalikan error 422 Unprocessable EntityPenyebab umum:

ID subscription atau ID produk tidak valid
Subscription tidak dalam state aktif
Parameter wajib tidak ada
Produk tidak tersedia untuk perubahan paket

Solusi:

Pastikan subscription ada dan aktif
Periksa ID produk valid dan tersedia
Pastikan semua parameter wajib diberikan
Tinjau dokumentasi API untuk persyaratan parameter

Immediate charge fails during plan change

Gejala: Perubahan paket dimulai, tetapi penagihan segera gagalPenyebab umum:

Dana pada metode pembayaran customer tidak mencukupi
Metode pembayaran kedaluwarsa atau tidak valid
Bank menolak transaksi
Deteksi fraud memblokir penagihan

Solusi:

Tangani event webhook payment.failed dengan tepat
Beri tahu customer untuk memperbarui metode pembayaran
Terapkan logika retry untuk kegagalan sementara
Pertimbangkan untuk mengizinkan perubahan paket meskipun penagihan segera gagal

Subscription on hold after plan change

Gejala: Penagihan perubahan paket gagal dan subscription berpindah ke state on_holdYang terjadi: Ketika penagihan perubahan paket gagal, subscription secara otomatis ditempatkan dalam state on_hold. Subscription tidak akan melakukan renewal secara otomatis sampai metode pembayaran diperbarui.Solusi: Perbarui metode pembayaran untuk mengaktifkan kembali subscriptionUntuk mengaktifkan kembali subscription dari state on_hold setelah perubahan paket gagal:

Perbarui metode pembayaran menggunakan Update Payment Method API
Pembuatan penagihan otomatis: API secara otomatis membuat penagihan untuk jumlah terutang yang tersisa
Pembuatan invoice: Invoice dibuat untuk penagihan tersebut
Pemrosesan pembayaran: Pembayaran diproses menggunakan metode pembayaran baru
Pengaktifan kembali: Setelah pembayaran berhasil, subscription diaktifkan kembali ke state 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

Event webhook yang perlu dipantau:

subscription.on_hold: Subscription ditahan (diterima saat penagihan perubahan paket gagal)
payment.succeeded: Pembayaran untuk jumlah terutang yang tersisa berhasil (setelah metode pembayaran diperbarui)
subscription.active: Subscription diaktifkan kembali setelah pembayaran berhasil

Praktik terbaik:

Beri tahu customer segera ketika penagihan perubahan paket gagal
Berikan instruksi yang jelas tentang cara memperbarui metode pembayaran
Pantau event webhook untuk melacak status pengaktifan kembali
Pertimbangkan untuk menerapkan logika retry otomatis bagi kegagalan pembayaran sementara

Update Payment Method API Reference

Lihat dokumentasi API lengkap untuk memperbarui metode pembayaran dan mengaktifkan kembali subscription.

Menguji Implementasi Anda

Ikuti langkah-langkah berikut untuk menguji implementasi perubahan paket subscription Anda secara menyeluruh:

Set up test environment

Gunakan API key test dan produk test
Buat subscription test dengan berbagai jenis paket
Konfigurasikan endpoint webhook test
Siapkan monitoring dan logging

Test different proration modes

Uji prorated_immediately dengan berbagai posisi dalam siklus billing
Uji difference_immediately untuk upgrade dan downgrade
Uji full_immediately untuk mengatur ulang siklus billing
Uji do_not_bill untuk perpindahan paket tanpa penagihan/kredit
Pastikan perhitungan kredit sudah benar

Test webhook handling

Pastikan semua event webhook yang relevan diterima
Uji verifikasi signature webhook
Tangani event webhook duplikat dengan baik
Uji skenario kegagalan pemrosesan webhook

Test error scenarios

Uji dengan ID subscription yang tidak valid
Uji dengan metode pembayaran yang kedaluwarsa
Uji kegagalan jaringan dan timeout
Uji dengan dana yang tidak mencukupi

Monitor in production

Siapkan alert untuk perubahan paket yang gagal
Pantau waktu pemrosesan webhook
Lacak tingkat keberhasilan perubahan paket
Tinjau tiket dukungan customer untuk masalah perubahan paket

Penanganan Error

Tangani error API umum dengan baik dalam implementasi Anda:

HTTP Status Codes

200 OK

Permintaan perubahan paket berhasil diproses. Body respons adalah ChangePlanResponse dengan payment_id, payment_link, client_secret, dan expires_on. Keempatnya nullable, sehingga body diserialisasikan sebagai {} untuk perubahan off-session biasa; keempatnya terisi untuk permintaan collect_via_payment_link yang berhasil, yang mengembalikan handle checkout — lihat Mengumpulkan Pembayaran melalui Checkout Link. Jika on_payment_failure=prevent_change, perubahan paket tetap tertunda hingga pembayaran berhasil.

400 Bad Request

Parameter request tidak valid. Pastikan semua field wajib diberikan dan diformat dengan benar.

401 Unauthorized

API key tidak valid atau tidak ada. Pastikan DODO_PAYMENTS_API_KEY Anda benar dan memiliki permission yang sesuai.

409 Conflict

Perubahan paket yang tertunda sudah ada untuk subscription ini (PendingPlanChangeExists). Untuk perubahan yang dijadwalkan, batalkan dengan DELETE /subscriptions/{subscription_id}/change-plan/scheduled sebelum mengirimkan yang baru. Untuk perubahan payment-link yang tertunda, tidak ada endpoint pembatalan — subscription dapat menerima permintaan perubahan paket baru setelah pelanggan membayar atau link kedaluwarsa.

422 Unprocessable Entity

Subscription tidak dapat ditemukan, tidak aktif atau bersifat on-demand, atau permintaan tidak memenuhi syarat untuk collect_via_payment_link — bisnis belum mengaktifkan kapabilitas tersebut, effective_at bukan immediately, atau on_payment_failure bukan prevent_change. Lihat Persyaratan. ID subscription yang tidak ada atau bukan milik akun Anda akan ditampilkan di sini sebagai 422, bukan 404.

500 Internal Server Error

Terjadi error server. Coba lagi permintaan tersebut setelah jeda singkat.

Change Plan API

Plan Change Preview

Integration Guide

​Apa Itu Upgrade atau Downgrade Subscription?

​Kapan Menggunakan Perubahan Plan

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Preview Perubahan Plan

​Change Plan API

​Contoh Quick Start

​Mengumpulkan Pembayaran melalui Checkout Link

​Requirements

​Apa yang Terjadi Saat Link Belum Dibayar

​Mengelola Addon

​Menerapkan Kode Diskon

​Perilaku Diskon saat Perubahan Plan

​Mode Prorasi

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​difference_immediately

​do_not_bill

​Skenario contoh

​Cara setiap mode memproses billing

​Menangani Kegagalan Pembayaran

​Mode Kegagalan Pembayaran

​Kapan Menggunakan Setiap Mode

​Default Business & Collection

​Urutan resolusi

​Menangani webhook

​Jenis event yang perlu ditangani

​Memverifikasi signature dan menangani intent

​Praktik Terbaik

​Strategi Perubahan Paket

​Implementasi Webhook

​User Experience

​Masalah Umum dan Solusi

Update Payment Method API Reference

​Menguji Implementasi Anda

​Penanganan Error

​HTTP Status Codes

Apa Itu Upgrade atau Downgrade Subscription?

Kapan Menggunakan Perubahan Plan

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Preview Perubahan Plan

Change Plan API

Contoh Quick Start

Mengumpulkan Pembayaran melalui Checkout Link

Requirements

Apa yang Terjadi Saat Link Belum Dibayar

Mengelola Addon

Menerapkan Kode Diskon

Perilaku Diskon saat Perubahan Plan

Mode Prorasi

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

`difference_immediately`

`do_not_bill`

Skenario contoh

Cara setiap mode memproses billing

Menangani Kegagalan Pembayaran

Mode Kegagalan Pembayaran

Kapan Menggunakan Setiap Mode

Default Business & Collection

Urutan resolusi

Menangani webhook

Jenis event yang perlu ditangani

Memverifikasi signature dan menangani intent

Praktik Terbaik

Strategi Perubahan Paket

Implementasi Webhook

User Experience

Masalah Umum dan Solusi

Menguji Implementasi Anda

Penanganan Error

HTTP Status Codes