Referensi API Ubah Rencana
Pratinjau API Perubahan Rencana
Panduan Integrasi Langganan
Apa itu upgrade atau downgrade langganan?
Mengubah rencana memungkinkan Anda memindahkan pelanggan antara tingkat atau kuantitas langganan. Gunakan ini untuk:- Menyesuaikan harga dengan penggunaan atau fitur
- Beralih dari bulanan ke tahunan (atau sebaliknya)
- Menyesuaikan kuantitas untuk produk berbasis kursi
Kapan menggunakan perubahan rencana
- Upgrade ketika pelanggan membutuhkan lebih banyak fitur, penggunaan, atau kursi
- Downgrade ketika penggunaan menurun
- Memigrasi pengguna ke produk atau harga baru tanpa membatalkan langganan mereka
Prasyarat
Sebelum menerapkan perubahan rencana langganan, pastikan Anda memiliki:- Akun pedagang Dodo Payments dengan produk langganan aktif
- Kredensial API (kunci API dan kunci rahasia webhook) dari dasbor
- Langganan aktif yang ada untuk dimodifikasi
- Titik akhir webhook yang dikonfigurasi untuk menangani peristiwa langganan
Panduan Implementasi Langkah-demi-Langkah
Ikuti panduan komprehensif ini untuk menerapkan perubahan rencana langganan di aplikasi Anda:Pahami Persyaratan Perubahan Rencana
- Produk langganan mana yang dapat diubah ke yang lain
- Mode proration mana yang sesuai dengan model bisnis Anda
- Cara menangani perubahan rencana yang gagal dengan baik
- Peristiwa webhook mana yang harus dilacak untuk manajemen status
Pilih Strategi Proration Anda
- prorated_immediately
- difference_immediately
- full_immediately
- Menghitung jumlah prorata yang tepat berdasarkan waktu siklus yang tersisa
- Mengenakan biaya jumlah prorata berdasarkan waktu yang tidak terpakai yang tersisa dalam siklus
- Memberikan penagihan yang transparan kepada pelanggan
Terapkan API Ubah Rencana
prorated_immediately, full_immediately, atau difference_immediately.Tangani Peristiwa Webhook
subscription.active: Perubahan rencana berhasil, langganan diperbaruisubscription.plan_changed: Rencana langganan diubah (upgrade/downgrade/pembaruan addon)subscription.on_hold: Biaya perubahan rencana gagal, langganan ditangguhkanpayment.succeeded: Biaya segera untuk perubahan rencana berhasilpayment.failed: Biaya segera gagal
Perbarui Status Aplikasi Anda
- Berikan/ambil fitur berdasarkan rencana baru
- Perbarui dasbor pelanggan dengan detail rencana baru
- Kirim email konfirmasi tentang perubahan rencana
- Catat perubahan penagihan untuk tujuan audit
Uji dan Pantau
- Uji semua mode proration dengan berbagai skenario
- Verifikasi penanganan webhook berfungsi dengan benar
- Pantau tingkat keberhasilan perubahan rencana
- Siapkan peringatan untuk perubahan rencana yang gagal
Pratinjau Perubahan Rencana
Sebelum berkomitmen pada perubahan rencana, gunakan API Pratinjau untuk menunjukkan kepada pelanggan persis berapa biaya yang akan mereka bayar:- Node.js SDK
- Python SDK
API Ubah Rencana
Gunakan API Ubah Rencana untuk memodifikasi produk, kuantitas, dan perilaku proration untuk langganan aktif.Contoh mulai cepat
- Node.js SDK
- Python SDK
- Go SDK
- HTTP
invoice_id dan payment_id hanya dikembalikan ketika biaya segera dan/atau faktur dibuat selama perubahan rencana. Selalu bergantung pada peristiwa webhook (misalnya, payment.succeeded, subscription.plan_changed) untuk mengonfirmasi hasil.Mengelola Addons
Saat mengubah rencana langganan, Anda juga dapat memodifikasi addons:Mode Proration
Pilih cara menagih pelanggan saat mengubah rencana:prorated_immediately
- Mengenakan biaya untuk selisih parsial dalam siklus saat ini
- Jika dalam masa percobaan, mengenakan biaya segera dan beralih ke rencana baru sekarang
- Downgrade: dapat menghasilkan kredit prorata yang diterapkan pada pembaruan di masa mendatang
full_immediately
- Mengenakan biaya penuh untuk rencana baru segera
- Mengabaikan waktu yang tersisa dari rencana lama
difference_immediately bersifat spesifik langganan dan berbeda dari Kredit Pelanggan. Mereka secara otomatis diterapkan pada pembaruan di masa mendatang dari langganan yang sama dan tidak dapat dipindahkan antar langganan.difference_immediately
- Upgrade: segera kenakan biaya selisih harga antara rencana lama dan baru
- Downgrade: tambahkan nilai yang tersisa sebagai kredit internal ke langganan dan terapkan secara otomatis pada pembaruan
Skenario Contoh
Upgrade: Basic ($30) → Pro ($80) dengan difference_immediately
Upgrade: Basic ($30) → Pro ($80) dengan difference_immediately
Downgrade: Plus ($50) → Starter ($20) dengan difference_immediately
Downgrade: Plus ($50) → Starter ($20) dengan difference_immediately
Upgrade di tengah siklus dengan prorated_immediately
Upgrade di tengah siklus dengan prorated_immediately
Reset penagihan dengan full_immediately
Reset penagihan dengan full_immediately
Menangani webhook
Lacak status langganan melalui webhook untuk mengonfirmasi perubahan rencana dan pembayaran.Jenis peristiwa yang harus ditangani
subscription.active: langganan diaktifkansubscription.plan_changed: rencana langganan diubah (upgrade/downgrade/perubahan addon)subscription.on_hold: biaya gagal, langganan ditangguhkansubscription.renewed: pembaruan berhasilpayment.succeeded: pembayaran untuk perubahan rencana atau pembaruan berhasilpayment.failed: pembayaran gagal
Verifikasi tanda tangan dan tangani niat
- Next.js Route Handler
- Express.js
Praktik Terbaik
Ikuti rekomendasi ini untuk perubahan rencana langganan yang andal:Strategi Perubahan Rencana
- Uji secara menyeluruh: Selalu uji perubahan rencana dalam mode uji sebelum produksi
- Pilih proration dengan hati-hati: Pilih mode proration yang sesuai dengan model bisnis Anda
- Tangani kegagalan dengan baik: Terapkan penanganan kesalahan yang tepat dan logika pengulangan
- Pantau tingkat keberhasilan: Lacak tingkat keberhasilan/kegagalan perubahan rencana dan selidiki masalah
Implementasi Webhook
- Verifikasi tanda tangan: Selalu validasi tanda tangan webhook untuk memastikan keaslian
- Terapkan idempotensi: Tangani peristiwa webhook duplikat dengan baik
- Proses secara asinkron: Jangan memblokir respons webhook dengan operasi berat
- Catat semuanya: Pertahankan log yang rinci untuk tujuan debugging dan audit
Pengalaman Pengguna
- Komunikasikan dengan jelas: Informasikan pelanggan tentang perubahan penagihan dan waktu
- Berikan konfirmasi: Kirim email konfirmasi untuk perubahan rencana yang berhasil
- Tangani kasus tepi: Pertimbangkan periode percobaan, proration, dan pembayaran yang gagal
- Perbarui UI segera: Refleksikan perubahan rencana dalam antarmuka aplikasi Anda
Masalah Umum dan Solusi
Atasi masalah umum yang dihadapi selama perubahan rencana langganan:Biaya dibuat tetapi langganan tidak diperbarui
Biaya dibuat tetapi langganan tidak diperbarui
- Pemrosesan webhook gagal atau tertunda
- Status aplikasi tidak diperbarui setelah menerima webhook
- Masalah transaksi basis data selama pembaruan status
- Terapkan penanganan webhook yang kuat dengan logika pengulangan
- Gunakan operasi idempotent untuk pembaruan status
- Tambahkan pemantauan untuk mendeteksi dan memberi tahu tentang peristiwa webhook yang terlewat
- Verifikasi titik akhir webhook dapat diakses dan merespons dengan benar
Kredit tidak diterapkan setelah downgrade
Kredit tidak diterapkan setelah downgrade
- Harapan mode proration: downgrade mengkredit selisih harga penuh rencana dengan
difference_immediately, sementaraprorated_immediatelymembuat kredit prorata berdasarkan waktu yang tersisa dalam siklus - Kredit bersifat spesifik langganan dan tidak dapat dipindahkan antar langganan
- Saldo kredit tidak terlihat di dasbor pelanggan
- Gunakan
difference_immediatelyuntuk downgrade ketika Anda ingin kredit otomatis - Jelaskan kepada pelanggan bahwa kredit diterapkan pada pembaruan di masa mendatang dari langganan yang sama
- Terapkan portal pelanggan untuk menunjukkan saldo kredit
- Periksa pratinjau faktur berikutnya untuk melihat kredit yang diterapkan
Verifikasi tanda tangan webhook gagal
Verifikasi tanda tangan webhook gagal
- Kunci rahasia webhook yang salah
- Badan permintaan mentah dimodifikasi sebelum verifikasi tanda tangan
- Algoritma verifikasi tanda tangan yang salah
- Verifikasi Anda menggunakan
DODO_WEBHOOK_SECRETyang benar dari dasbor - Baca badan permintaan mentah sebelum middleware parsing JSON apa pun
- Gunakan pustaka verifikasi webhook standar untuk platform Anda
- Uji verifikasi tanda tangan webhook di lingkungan pengembangan
Perubahan rencana gagal dengan kesalahan 422
Perubahan rencana gagal dengan kesalahan 422
- ID langganan atau ID produk tidak valid
- Langganan tidak dalam status aktif
- Parameter yang diperlukan hilang
- Produk tidak tersedia untuk perubahan rencana
- Verifikasi langganan ada dan aktif
- Periksa ID produk valid dan tersedia
- Pastikan semua parameter yang diperlukan disediakan
- Tinjau dokumentasi API untuk persyaratan parameter
Biaya segera gagal selama perubahan rencana
Biaya segera gagal selama perubahan rencana
- Dana tidak mencukupi pada metode pembayaran pelanggan
- Metode pembayaran kedaluwarsa atau tidak valid
- Bank menolak transaksi
- Deteksi penipuan memblokir biaya
- Tangani peristiwa webhook
payment.faileddengan tepat - Beri tahu pelanggan untuk memperbarui metode pembayaran
- Terapkan logika pengulangan untuk kegagalan sementara
- Pertimbangkan untuk mengizinkan perubahan rencana dengan biaya segera yang gagal
Langganan ditangguhkan setelah perubahan rencana
Langganan ditangguhkan setelah perubahan rencana
on_holdApa yang terjadi:
Ketika biaya perubahan rencana gagal, langganan secara 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 rencana yang gagal:- Perbarui metode pembayaran menggunakan API Perbarui Metode Pembayaran
- Pembuatan biaya otomatis: API secara otomatis membuat biaya untuk tunggakan yang tersisa
- Pembuatan faktur: Faktur dibuat untuk biaya tersebut
- Pemrosesan pembayaran: Pembayaran diproses menggunakan metode pembayaran baru
- Reaktivasi: Setelah pembayaran berhasil, langganan diaktifkan kembali ke status
active
subscription.on_hold: Langganan ditempatkan pada hold (diperoleh ketika biaya perubahan rencana gagal)payment.succeeded: Pembayaran untuk tunggakan yang tersisa berhasil (setelah memperbarui metode pembayaran)subscription.active: Langganan diaktifkan kembali setelah pembayaran berhasil
- Segera beri tahu pelanggan ketika biaya perubahan rencana gagal
- Berikan instruksi yang jelas tentang cara memperbarui metode pembayaran mereka
- Pantau peristiwa webhook untuk melacak status reaktivasi
- Pertimbangkan untuk menerapkan logika pengulangan otomatis untuk kegagalan pembayaran sementara
Referensi API Perbarui Metode Pembayaran
Menguji Implementasi Anda
Ikuti langkah-langkah ini untuk menguji implementasi perubahan rencana langganan Anda secara menyeluruh:Siapkan lingkungan uji
- Gunakan kunci API uji dan produk uji
- Buat langganan uji dengan berbagai jenis rencana
- Konfigurasi titik akhir webhook uji
- Siapkan pemantauan dan pencatatan
Uji berbagai mode proration
- Uji
prorated_immediatelydengan berbagai posisi siklus penagihan - Uji
difference_immediatelyuntuk upgrade dan downgrade - Uji
full_immediatelyuntuk mengatur ulang siklus penagihan - Verifikasi perhitungan kredit sudah benar
Uji penanganan webhook
- Verifikasi semua peristiwa webhook yang relevan diterima
- Uji verifikasi tanda tangan webhook
- Tangani peristiwa webhook duplikat dengan baik
- Uji skenario kegagalan pemrosesan webhook
Uji skenario kesalahan
- Uji dengan ID langganan yang tidak valid
- Uji dengan metode pembayaran yang kedaluwarsa
- Uji kegagalan jaringan dan timeout
- Uji dengan dana yang tidak mencukupi
Pantau di produksi
- Siapkan peringatan untuk perubahan rencana yang gagal
- Pantau waktu pemrosesan webhook
- Lacak tingkat keberhasilan perubahan rencana
- Tinjau tiket dukungan pelanggan untuk masalah perubahan rencana
Penanganan Kesalahan
Tangani kesalahan API umum dengan baik dalam implementasi Anda:Kode Status HTTP
200 OK
200 OK
400 Bad Request
400 Bad Request
401 Unauthorized
401 Unauthorized
404 Not Found
404 Not Found
422 Unprocessable Entity
422 Unprocessable Entity
500 Internal Server Error
500 Internal Server Error
Format Respons Kesalahan
Langkah Selanjutnya
- Tinjau API Ubah Rencana
- Jelajahi Kredit Pelanggan
- Terapkan peringatan untuk
subscription.on_hold - Lihat Panduan Integrasi Webhook