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

ID produk baru yang digunakan untuk mengubah langganan.

integer

wajib

Jumlah unit untuk paket baru (untuk produk berbasis seat).

string

wajib

Cara menangani penagihan langsung: prorated_immediately, full_immediately, difference_immediately, atau 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

Mengontrol perilaku saat pembayaran perubahan paket gagal:

prevent_change: Pertahankan langganan pada paket saat ini hingga pembayaran berhasil
apply_change (default): Terapkan perubahan paket segera terlepas dari hasil pembayaran

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

boolean

Kumpulkan jumlah perubahan paket melalui payment link, bukan dengan menagih metode pembayaran tersimpan milik langganan. Pelanggan 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.

string

URL yang menerima pelanggan setelah mereka membayar payment link. Pengalihan menambahkan subscription_id, payment_id, dan status. Memerlukan collect_via_payment_link: true; jika tidak, request gagal dengan 422. Lihat Mengalihkan Pelanggan Setelah Pembayaran.

boolean

default:"false"

Batalkan payment link yang belum dibayar untuk perubahan paket yang tertunda, sehingga request ini menggantikannya. Pembayaran yang sudah dibayar atau sedang berlangsung mengembalikan 409. Lihat Mengganti Payment Link yang Tertunda. Diabaikan oleh route preview.

array

Kode diskon stacked opsional untuk diterapkan pada paket baru (maks. 20, diterapkan sesuai urutan array). Perilakunya bergantung pada nilai yang dikirim:

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 langganan.
["CODE_A", "CODE_B", ...] — mengganti semua diskon yang ada dengan set stacked ini.

string

usang

Deprecated — gunakan discount_codes untuk integrasi baru. Field ini masih berfungsi untuk kompatibilitas mundur, tetapi tidak dapat digabungkan dengan discount_codes dalam request yang sama.

string

default:"immediately"

Kapan perubahan paket diterapkan:

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

Handle Webhook Events

Siapkan penanganan webhook untuk melacak hasil perubahan paket:

subscription.active: Perubahan paket berhasil, langganan diperbarui
subscription.plan_changed: Paket langganan berubah (upgrade/downgrade/pembaruan addon)
subscription.on_hold: Tagihan perubahan paket gagal, renewal dihentikan
payment.succeeded: Tagihan langsung untuk perubahan paket berhasil
payment.failed: Tagihan 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 paket baru
Perbarui dashboard pelanggan dengan detail paket baru
Kirim email konfirmasi tentang perubahan paket
Catat perubahan penagihan untuk keperluan audit

Test and Monitor

Uji implementasi Anda secara menyeluruh:

Uji semua mode proration dengan berbagai skenario
Verifikasi bahwa penanganan webhook berfungsi dengan benar
Pantau tingkat keberhasilan perubahan paket
Siapkan alert untuk perubahan paket yang gagal

Implementasi perubahan paket langganan Anda kini siap digunakan di production.

Preview Perubahan Paket

Sebelum menetapkan perubahan paket, gunakan Preview API untuk menunjukkan kepada pelanggan jumlah yang akan ditagihkan secara tepat:

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

Dalam immediate_charge.summary, customer_credits adalah perubahan bersih pada saldo kredit pelanggan, dalam mata uang yang diberikan oleh customer_credits_currency. Ini adalah mata uang credit wallet pelanggan, yaitu mata uang langganan. Mata uang ini dapat berbeda dari currency pada ringkasan, yang berlaku untuk total_amount dan tax. Misalnya, pelanggan yang membayar dalam INR untuk langganan USD akan melihat kredit dalam USD.

Change Plan API

Gunakan Change Plan API untuk mengubah produk, kuantitas, dan perilaku proration pada langganan 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 paket yang berhasil mengembalikan 200 OK segera — sebelum tagihan 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 yang ditagihkan
`proration_billing_mode: do_not_bill`	Semua `null` — tidak ada yang perlu ditagihkan
Tagihan langsung biasa (metode pembayaran tersimpan)	Semua `null`
`collect_via_payment_link: true` (link diterbitkan)	Semua terisi — handle checkout untuk pelanggan

Response ini mengonfirmasi bahwa request diterima, bukan bahwa tagihan berhasil. Untuk tagihan langsung biasa, hasilnya diselesaikan off-session segera setelah pemanggilan. Untuk request collect_via_payment_link, langganan tetap menggunakan paket saat ini hingga pelanggan menyelesaikan pembayaran.Konfirmasikan hasilnya melalui webhook (payment.succeeded, payment.failed, subscription.plan_changed) atau dengan membaca ulang langganan menggunakan GET /subscriptions/{subscription_id} — lihat Yang Terjadi Saat Link Belum Dibayar untuk kasus payment link.

Jika tagihan langsung gagal, langganan dapat berpindah ke subscription.on_hold hingga pembayaran berhasil.

Mengumpulkan Pembayaran melalui Checkout Link

Secara default, perubahan paket langsung menagih metode pembayaran tersimpan milik langganan. Atur collect_via_payment_link: true untuk mengarahkan pelanggan ke halaman checkout yang di-host — berguna jika tidak ada metode pembayaran tersimpan atau Anda ingin pelanggan mengonfirmasi harga baru secara aktif.

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

Persyaratan

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

Bisnis mengaktifkan capability allow_plan_change_via_payment_link (Settings → Subscriptions → Collect Plan Change Payments by Payment Link).
effective_at adalah immediately (default). Perubahan terjadwal (next_billing_date) tidak pernah memerlukan halaman checkout.
Request menetapkan on_payment_failure: prevent_change. apply_change yang eksplisit gagal dengan 422.

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

Jika perubahan menghasilkan nilai nol atau kredit, payment link tidak diterbitkan: payment_link dan field checkout lainnya dikembalikan sebagai null, dan perubahan diterapkan segera. Ini bukan 422. Panggil Preview Plan Change terlebih dahulu untuk memeriksa jumlah 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 handle checkout:

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

Yang Terjadi Saat Link Belum Dibayar

Langganan tetap menggunakan paket 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. Untuk mengganti perubahan yang tertunda, kirim request baru dengan cancel_older_payment_link: true. Lihat Mengganti Payment Link yang Tertunda.
Untuk mencoba lagi setelah pembayaran ditolak, panggil kembali change-plan untuk mendapatkan link baru.
Jika link tidak pernah dibayar, link berhenti berfungsi setelah expires_on — langganan secara otomatis menjadi bebas untuk menerima request perubahan paket baru tidak lama setelahnya.
Jika perubahan terjadwal sudah ada dan Anda menggantinya dengan cancel_scheduled_change_plan: true, jadwal asli tetap berlaku saat link belum dibayar dan baru dibatalkan setelah link dibayar — dalam transaksi yang sama saat paket baru diterapkan.

Setelah perubahan melalui payment link langsung diterbitkan, setiap request perubahan paket berikutnya pada langganan tersebut — termasuk preview tanpa efek samping — diblokir hingga link diselesaikan. Request change-plan dapat mengganti link dengan menetapkan cancel_older_payment_link: true. Preview mengabaikan field ini, sehingga preview tetap diblokir.

Mengalihkan Pelanggan Setelah Pembayaran

Atur return_url untuk mengarahkan pelanggan kembali ke situs Anda setelah mereka membayar link:

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

Setelah checkout, pelanggan diarahkan ke return_url dengan parameter query berikut:

Parameter	Nilai
`subscription_id`	Langganan yang menjadi tujuan perubahan paket.
`payment_id`	Pembayaran perubahan paket.
`status`	Status pembayaran perubahan paket, bukan status langganan: `active` saat dibayar, `failed` saat ditolak, `pending` saat sedang berlangsung.

Jika pembayaran gagal, langganan tetap aktif pada paket saat ini. Paket baru dapat diterapkan tidak lama setelah pengalihan, ketika webhook pembayaran tiba, jadi baca kembali langganan sebelum menampilkan paket baru. return_url memerlukan collect_via_payment_link: true. Tanpanya, request gagal dengan 422.

Mengganti Payment Link yang Tertunda

Jika pelanggan meninggalkan checkout tanpa membayar, tetapkan cancel_older_payment_link: true pada request change-plan berikutnya. Dodo Payments membatalkan link yang belum dibayar, dan perubahan paket baru menggantikan perubahan yang tertunda. Link yang dibatalkan tidak lagi menerima pembayaran, bahkan pada halaman checkout yang sudah terbuka.

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

Request divalidasi sebelum link dibatalkan, sehingga request yang tidak valid mempertahankan link pelanggan. Link hanya dibatalkan jika pelanggan belum mulai membayar:

Pembayaran sebelumnya	Response
Belum dibuka, sudah dibuka tetapi belum dibayar, atau ditolak	`200` dengan link baru.
Pelanggan sedang membayar, misalnya saat 3D Secure	`409` `PLAN_CHANGE_PAYMENT_IN_PROGRESS`. Coba lagi setelah pembayaran selesai atau gagal.
Sudah dibayar	`409` `PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED`. Jangan coba lagi: perubahan paket sebelumnya diterapkan.
Link tidak dapat dibatalkan	`503` `PLAN_CHANGE_LINK_CANCEL_FAILED`. Tidak ada yang berubah, jadi Anda dapat mencoba lagi.

Setiap request change-plan menerbitkan invoice sendiri. Perubahan paket yang diganti dan invoicenya dibatalkan. Jika tidak ada perubahan paket yang tertunda, cancel_older_payment_link tidak berpengaruh.

Pemeriksaan yang berjalan setelah validasi, misalnya jumlah tagihan minimum, tetap dapat gagal setelah link dibatalkan. Langganan kemudian tetap menggunakan paket saat ini tanpa link yang terbuka. Kirim kembali request untuk menerbitkan link baru.

Mengelola Addon

Saat mengubah paket langganan, 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 proration dan akan ditagihkan sesuai mode proration yang dipilih.

Menerapkan Kode Diskon

Terapkan satu atau beberapa kode diskon stacked saat mengubah paket langganan (maks. 20, diterapkan sesuai urutan 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 Paket

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 langganan.
`["CODE_A", "CODE_B", ...]`	Mengganti semua diskon yang ada dengan set stacked ini, yang divalidasi dan diterapkan sesuai urutan array.

Field tunggal discount_code pada endpoint ini deprecated, tetapi masih berfungsi untuk kompatibilitas mundur — integrasi yang ada tidak perlu segera berubah. Field ini tidak dapat digabungkan dengan discount_codes dalam request yang sama. Migrasikan ke bentuk array jika sudah memungkinkan.

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

Mode Proration

Pilih cara menagih pelanggan saat mengubah paket:

`prorated_immediately`

Mengkreditkan bagian yang tidak digunakan dari siklus saat ini — paket dasar, kuantitas, dan addon — secara prorata berdasarkan sisa waktu
Kemudian menagihkan siklus penuh pada paket, kuantitas, dan addon baru. Tagihan itu sendiri tidak pernah diprorata
Tagihan langsung bersih = (siklus baru penuh) − (fraksi tersisa × siklus lama penuh)
Jika kredit melebihi tagihan siklus baru (umum pada downgrade), selisihnya disimpan sebagai kredit berskala langganan untuk renewal mendatang
Jika sedang trial, tagih segera dan beralih ke paket baru sekarang

`full_immediately`

Menagihkan jumlah penuh paket baru segera
Mengabaikan waktu tersisa dari paket lama — tidak ada kredit untuk siklus saat ini

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

`difference_immediately`

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

`do_not_bill`

Tidak ada tagihan atau kredit yang dihitung
Pelanggan segera beralih ke paket baru tanpa penyesuaian penagihan
Siklus penagihan tetap tidak berubah
Cocok untuk migrasi sebagai bentuk layanan, perpindahan ke paket gratis, atau menyerap selisih biaya

Fitur	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Tagihan upgrade	Siklus baru penuh, dikurangi kredit untuk waktu yang tidak digunakan	Selisih harga penuh antara paket	Harga paket baru penuh	Tanpa tagihan
Kredit downgrade	Kredit untuk waktu yang tidak digunakan, dikurangi satu siklus baru penuh	Selisih harga penuh sebagai kredit	Tanpa kredit	Tanpa kredit
Siklus penagihan	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, jumlah penuh ditagih	Tanggal akhir trial tetap, tanpa tagihan
Cocok untuk	Mengkreditkan waktu yang tidak digunakan	Perhitungan upgrade/downgrade sederhana	Mengatur ulang siklus penagihan	Migrasi gratis atau perpindahan sebagai bentuk layanan
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 penagihan: 30 hari, dimulai pada 1 Januari
Perubahan paket terjadi pada 16 Januari (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 Penagihan

Pilih prorated_immediately untuk mengkreditkan waktu yang tidak digunakan pada paket lama sambil menagihkan satu siklus penuh 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 berpindah paket tanpa penyesuaian penagihan apa pun.

Menangani Kegagalan Pembayaran

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

Mode Kegagalan Pembayaran

prevent_change (Recommended for critical upgrades)
apply_change (Default)

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

Perubahan paket ditandai sebagai “pending”
Pelanggan tetap memiliki akses ke paket saat ini
Langganan berpindah ke status active hanya setelah pembayaran berhasil
Berguna saat 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 terlepas dari hasil pembayaran.

Perubahan paket diterapkan meskipun pembayaran gagal
Pelanggan langsung memperoleh akses ke paket baru
Langganan dapat berpindah ke on_hold jika pembayaran gagal
Cocok untuk upgrade yang tidak kritis atau saat Anda memercayai pelanggan

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 bisnis 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`	Mencegah penggunaan tanpa pembayaran
Downgrade paket	`apply_change`	Pelanggan mengurangi pengeluaran
Pelanggan enterprise tepercaya	`apply_change`	Risiko tidak membayar lebih rendah
Konversi trial ke berbayar	`prevent_change`	Momen pembayaran yang penting

Default Bisnis & Collection

Atur perilaku default upgrade dan downgrade di tingkat bisnis melalui Settings → Subscriptions. Default ini berlaku untuk semua perubahan paket melalui customer portal dan dapat ditimpa per product collection. Default terpisah tersedia 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 pelanggan ditagih	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Jika pembayaran pelanggan gagal	`on_payment_failure`	`apply_change`	`apply_change`

Konfigurasikan default bisnis melalui Settings → Subscriptions, dan override collection pada setiap product collection. Setiap field collection bersifat independen — biarkan tidak diatur untuk mewarisi default bisnis, atau tetapkan nilai untuk menimpanya.

Urutan Resolusi

Untuk perubahan paket apa pun, setiap pengaturan ditentukan 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 memiliki prioritas. Default bisnis 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 pelanggan membayar selisih dan langsung memperoleh akses, serta pertahankan downgrade pada next_billing_date agar pelanggan tetap menggunakan paket saat ini hingga siklus berakhir.

Menangani Webhook

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

Jenis Event yang Ditangani

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

Jalankan logika bisnis berdasarkan event langganan dan gunakan event pembayaran 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_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);

Untuk skema payload terperinci, lihat payload webhook Subscription dan payload webhook Payment.

Praktik Terbaik

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 percobaan ulang yang tepat
Pantau tingkat keberhasilan: Lacak tingkat keberhasilan/kegagalan perubahan paket dan selidiki masalah

Implementasi Webhook

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

User Experience

Berkomunikasi dengan jelas: Informasikan pelanggan tentang perubahan dan waktu penagihan
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 di interface aplikasi Anda

Masalah Umum dan Solusi

Atasi masalah umum yang ditemukan selama perubahan paket langganan:

Charge created but subscription not updated

Gejala: Panggilan API berhasil tetapi langganan 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 dengan logika percobaan ulang
Gunakan operasi idempoten untuk pembaruan state
Tambahkan monitoring untuk mendeteksi dan memberi alert atas event webhook yang terlewat
Verifikasi endpoint webhook dapat diakses dan merespons dengan benar

Credits not applied after downgrade

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

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

Solusi:

Gunakan difference_immediately untuk downgrade saat Anda menginginkan kredit otomatis
Jelaskan kepada pelanggan bahwa kredit berlaku untuk renewal mendatang pada langganan 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:

Webhook secret key salah
Raw request body diubah sebelum verifikasi signature
Algoritma verifikasi signature salah

Solusi:

Verifikasi bahwa Anda menggunakan DODO_PAYMENTS_WEBHOOK_KEY 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 langganan atau ID produk tidak valid
Langganan tidak dalam status aktif
Parameter wajib tidak ada
Produk tidak tersedia untuk perubahan paket

Solusi:

Verifikasi langganan 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 tagihan langsung gagalPenyebab umum:

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

Solusi:

Tangani event webhook payment.failed dengan tepat
Beri tahu pelanggan untuk memperbarui metode pembayaran
Terapkan logika percobaan ulang untuk kegagalan sementara
Pertimbangkan untuk mengizinkan perubahan paket dengan tagihan langsung yang gagal

Subscription on hold after plan change

Gejala: Tagihan perubahan paket gagal dan langganan berpindah ke status on_holdYang terjadi: Saat tagihan perubahan paket gagal, langganan otomatis ditempatkan dalam status on_hold. Langganan tidak akan diperbarui secara otomatis hingga metode pembayaran diperbarui.Solusi: Perbarui metode pembayaran untuk mengaktifkan kembali langgananUntuk mengaktifkan kembali langganan dari status on_hold setelah perubahan paket gagal:

Perbarui metode pembayaran menggunakan Update Payment Method API
Pembuatan tagihan otomatis: API otomatis membuat tagihan untuk iuran yang tersisa
Pembuatan invoice: Invoice dibuat untuk tagihan tersebut
Pemrosesan pembayaran: Pembayaran diproses menggunakan metode pembayaran baru
Reaktivasi: Setelah pembayaran berhasil, langganan diaktifkan kembali ke status 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: Langganan ditangguhkan (diterima saat tagihan perubahan paket gagal)
payment.succeeded: Pembayaran iuran tersisa berhasil (setelah metode pembayaran diperbarui)
subscription.active: Langganan diaktifkan kembali setelah pembayaran berhasil

Praktik terbaik:

Beri tahu pelanggan segera saat tagihan perubahan paket gagal
Berikan instruksi yang jelas tentang cara memperbarui metode pembayaran
Pantau event webhook untuk melacak status reaktivasi
Pertimbangkan untuk menerapkan logika percobaan ulang otomatis untuk kegagalan pembayaran sementara

Update Payment Method API Reference

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

Menguji Implementasi Anda

Uji implementasi perubahan paket langganan Anda secara menyeluruh:

Set up test environment

Gunakan API key test dan produk test
Buat langganan 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 penagihan
Uji difference_immediately untuk upgrade dan downgrade
Uji full_immediately untuk mengatur ulang siklus penagihan
Uji do_not_bill untuk perpindahan paket tanpa tagihan/kredit
Verifikasi penghitungan kredit sudah benar

Test webhook handling

Verifikasi 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 langganan 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 pelanggan terkait masalah perubahan paket

Penanganan Error

Tangani error API umum dengan baik dalam implementasi Anda:

HTTP Status Codes

200 OK

Request perubahan paket berhasil diproses. Body response adalah ChangePlanResponse dengan payment_id, payment_link, client_secret, dan expires_on. Keempatnya nullable, sehingga body diserialisasikan sebagai {} untuk perubahan off-session biasa; semuanya terisi untuk request 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. Periksa bahwa semua field wajib diberikan dan diformat dengan benar.

401 Unauthorized

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

409 Conflict

Perubahan paket yang tertunda sudah ada untuk langganan ini (PendingPlanChangeExists). Untuk perubahan terjadwal, batalkan dengan DELETE /subscriptions/{subscription_id}/change-plan/scheduled sebelum mengirimkan perubahan baru. Untuk perubahan payment-link yang tertunda, kirim request baru dengan cancel_older_payment_link: true untuk menggantinya. Lihat Mengganti Payment Link yang Tertunda.Dengan cancel_older_payment_link: true, 409 berarti pelanggan sedang membayar link sebelumnya (PLAN_CHANGE_PAYMENT_IN_PROGRESS) atau sudah membayarnya (PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED).

503 Service Unavailable

Dengan cancel_older_payment_link: true, payment link sebelumnya tidak dapat dibatalkan (PLAN_CHANGE_LINK_CANCEL_FAILED). Tidak ada yang berubah, sehingga Anda dapat mencoba kembali request tersebut.

422 Unprocessable Entity

Langganan tidak aktif atau on-demand, atau request tidak memenuhi syarat untuk collect_via_payment_link — bisnis tidak mengaktifkan capability tersebut, effective_at bukan immediately, atau on_payment_failure bukan prevent_change. Lihat Persyaratan. ID langganan yang tidak ada atau bukan milik akun Anda mengembalikan 404 dengan code NOT_FOUND.

500 Internal Server Error

Terjadi error server. Coba lagi request setelah jeda singkat.

Format Error Response

Error mengembalikan body JSON dengan code dan message yang dapat dibaca manusia:

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

Lihat Error Codes untuk daftar lengkap.

Langkah Berikutnya

Tinjau Change Plan API
Jelajahi Credit-Based Billing
Implementasikan alert untuk subscription.on_hold
Lihat Webhook Integration Guide

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 Paket

​Change Plan API

​Contoh Quick Start

​Mengumpulkan Pembayaran melalui Checkout Link

​Persyaratan

​Yang Terjadi Saat Link Belum Dibayar

​Mengalihkan Pelanggan Setelah Pembayaran

​Mengganti Payment Link yang Tertunda

​Mengelola Addon

​Menerapkan Kode Diskon

​Perilaku Diskon Saat Perubahan Paket

​Mode Proration

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Skenario Contoh

​Cara Setiap Mode Memproses Penagihan

​Menangani Kegagalan Pembayaran

​Mode Kegagalan Pembayaran

​Kapan Menggunakan Setiap Mode

​Default Bisnis & Collection

​Urutan Resolusi

​Menangani Webhook

​Jenis Event yang 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

​Format Error Response

​Langkah Berikutnya

Apa Itu Upgrade atau Downgrade Subscription?

Kapan Menggunakan Perubahan Plan

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Preview Perubahan Paket

Change Plan API

Contoh Quick Start

Mengumpulkan Pembayaran melalui Checkout Link

Persyaratan

Yang Terjadi Saat Link Belum Dibayar

Mengalihkan Pelanggan Setelah Pembayaran

Mengganti Payment Link yang Tertunda

Mengelola Addon

Menerapkan Kode Diskon

Perilaku Diskon Saat Perubahan Paket

Mode Proration

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Skenario Contoh

Cara Setiap Mode Memproses Penagihan

Menangani Kegagalan Pembayaran

Mode Kegagalan Pembayaran

Kapan Menggunakan Setiap Mode

Default Bisnis & Collection

Urutan Resolusi

Menangani Webhook

Jenis Event yang 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

Format Error Response

Langkah Berikutnya