Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.
Upgrade & Downgrade
Control plan changes with proration and quantity updates.
On‑Demand Subscriptions
Authorize a mandate now and charge later with custom amounts.
Customer Portal
Let customers manage plans, billing, and cancellations.
Subscription Webhooks
React to lifecycle events like created, renewed, and canceled.
What Are Subscriptions?
Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:- SaaS licenses: Apps, APIs, or platform access
- Memberships: Communities, programs, or clubs
- Digital content: Courses, media, or premium content
- Support plans: SLAs, success packages, or maintenance
Key Benefits
- Predictable revenue: Recurring billing with automated renewals
- Flexible cycles: Monthly, annual, custom intervals, and trials
- Plan agility: Proration for upgrades and downgrades
- Add‑ons and seats: Attach optional, quantifiable upgrades
- Seamless checkout: Hosted checkout and customer portal
- Developer-first: Clear APIs for creation, changes, and usage tracking
Creating Subscriptions
Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.Subscription product creation
Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.Product details
- Product Name (required): The display name shown in checkout, customer portal, and invoices.
- Product Description (required): A clear value statement that appears in checkout and invoices.
- Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
- Brand: Associate the product with a specific brand for theming and emails.
- Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.
Pricing
- Pricing Type: Choose Subscription (this guide). Alternatives are Single Payment and Usage Based Billing.
- Price (required): Base recurring price with currency.
- Discount Applicable (%): Optional percentage discount applied to the base price; reflected in checkout and invoices.
- Repeat payment every (required): Interval for renewals, e.g., every 1 Month. Select the cadence (months or years) and quantity.
- Subscription Period (required): Total term for which the subscription remains active (e.g., 10 Years). After this period ends, renewals stop unless extended.
- Trial Period Days (required): Set trial length in days. Use 0 to disable trials. The first charge occurs automatically when the trial ends.
- Select add‑on: Attach up to 10 add‑ons that customers can purchase alongside the base plan.
Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.
Advanced settings
- Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
- Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
- Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
- Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.
Subscription Trials
Trials let customers access subscriptions without immediate payment. The first charge occurs automatically when the trial ends.Configuring Trials
Set Trial Period Days in the product pricing section (use0 to disable). You can override this when creating subscriptions:
Detecting Trial Status
To determine if a subscription is in trial, retrieve the list of payments for the subscription. If there is exactly one payment with amount 0, the subscription is in trial period:Updating Trial Period
Extend the trial by updatingnext_billing_date:
Subscription Plan Changes
Plan changes let you upgrade or downgrade subscriptions, adjust quantities, or migrate to different products. Depending on the proration mode you select, a change may trigger an immediate charge, create credit, or apply no billing adjustment.Product Collections
Group related products into collections to enable seamless upgrade/downgrade paths in the Customer Portal.
Proration Modes
Choose how customers are billed when changing plans:Quick comparison of the four proration modes:
prorated_immediately | difference_immediately | full_immediately | do_not_bill | |
|---|---|---|---|---|
| Upgrade | Biaya prorata untuk hari yang tersisa | Selisih harga penuh dikenakan | Harga paket baru penuh dikenakan | Tidak ada biaya — langsung beralih |
| Downgrade | Kredit prorata untuk hari yang tersisa | Selisih harga penuh sebagai kredit | Tidak ada kredit, biaya penuh | Tidak ada kredit — langsung beralih |
| Siklus penagihan | Direset ke hari ini | Direset ke hari ini | Direset ke hari ini | Tetap sama |
| Terbaik untuk | Penagihan berbasis waktu yang adil | Perubahan tier sederhana | Reset siklus penagihan | Migrasi gratis atau penggantian sebagai keramahan |
prorated_immediately
Charges prorated amount based on remaining time in the current billing cycle. Best for fair billing that accounts for unused time.
difference_immediately
Charges the price difference immediately (upgrade) or adds credit for future renewals (downgrade). Best for simple upgrade/downgrade scenarios.
Credits from downgrades using
difference_immediately are subscription-scoped and auto-applied to future renewals. They’re distinct from Credit-Based Billing entitlements.difference_immediately, the unused value becomes a subscription-scoped credit that automatically offsets future renewals:
full_immediately
Charges full new plan amount immediately, ignoring remaining time. Best for resetting billing cycles.
do_not_bill
Switches to the new plan without any billing adjustment. No proration charges, no credits — the customer simply moves to the new plan. Best for courtesy migrations, free plan switches, or scenarios where you want to absorb the cost difference.
Example: Prorated upgrade calculation
Example: Prorated upgrade calculation
Scenario: Customer on Basic (80/month) on day 16 of a 30-day cycle using Pembaharuan berikutnya pada 15 Februari (16 Januari + 30 hari): $80.00/bulan.
prorated_immediately.Example: Downgrade credit calculation
Example: Downgrade credit calculation
Scenario: Customer on Pro (20/month) using The $60 credit auto-applies to future renewals:
difference_immediately.- Renewal 1: 20 (credit) = **40 credit remaining)
- Renewal 2: 20 (credit) = **20 credit remaining)
- Renewal 3: 20 (credit) = $0.00 (credit exhausted)
- Renewal 4: $20.00 (full price)
Learn more about how credits are managed in the Upgrade & Downgrade Guide.
Changing Plans with Add-ons
Modify add-ons when changing plans. Add-ons are included in proration calculations:Plan changes trigger immediate charges. Failed charges may move the subscription to
on_hold status. Track changes via subscription.plan_changed webhook events.Previewing Plan Changes
Before committing to a plan change, preview the exact charge and resulting subscription:Preview Change Plan API
Preview plan changes before committing to them.
Subscription States
Sebuah langganan bergerak melalui serangkaian status yang telah ditentukan selama masa hidupnya. Tabel ini adalah referensi untuk setiap status, penyebabnya, dan cara (atau apakah) Anda dapat memulihkannya.| Status | Artinya | Dapat Pulih? | Jalur Pemulihan / langkah selanjutnya |
|---|---|---|---|
pending | Langganan sedang dibuat atau diproses | — | Tunggu subscription.active (atau subscription.failed) |
active | Langganan aktif dan akan diperbarui secara otomatis | — | Tidak ada tindakan yang diperlukan |
on_hold | Pembayaran pembaruan (atau biaya perubahan paket) gagal; langganan dijeda | Ya | Perbarui metode pembayaran untuk mengaktifkan kembali — secara otomatis melalui Payment Retries dan Dunning, atau secara manual melalui Update Payment Method API |
cancelled | Langganan dibatalkan dan tidak akan diperbarui | Hanya pembelian ulang | Pelanggan harus memulai langganan baru; Dunning dapat memantik pembelian ulang |
failed | Pembuatan langganan gagal (mandat awal atau pembayaran tidak berhasil) | Tidak — terminal | Pelanggan harus membuat langganan baru dengan metode pembayaran yang berfungsi |
expired | Langganan mencapai akhir masa berlakunya | — | Pelanggan harus memulai langganan baru jika diinginkan |
Mesin Status
Status Ditahan
Sebuah langganan masuk ke dalam statuson_hold ketika:
- Pembayaran pembaruan gagal (dana tidak mencukupi, kartu kedaluwarsa, dll.)
- Biaya perubahan paket gagal
- Otorisasi metode pembayaran gagal
Mengaktifkan Kembali dari Ditahan
Untuk mengaktifkan kembali langganan dari statuson_hold, perbarui metode pembayaran. Ini secara otomatis:
- Membuat biaya untuk hutang yang tersisa
- Menghasilkan faktur
- Memproses pembayaran menggunakan metode pembayaran baru
- Mengaktifkan kembali langganan ke status
activesetelah pembayaran berhasil
Setelah berhasil memperbarui metode pembayaran untuk langganan
on_hold, Anda akan menerima acara webhook payment.succeeded diikuti oleh subscription.active.Acara Webhook oleh Transisi
Setiap transisi memancarkan webhook sehingga Anda dapat menggerakkan logika hak tanpa pemindaian:| Transisi | Acara |
|---|---|
| Langganan diaktifkan | subscription.active |
| Pembaruan berhasil | subscription.renewed |
| Pembaruan gagal → jeda | subscription.on_hold |
| Pembuatan gagal | subscription.failed |
| Paket diperbarui/dikurangi | subscription.plan_changed |
| Dibatalkan | subscription.cancelled |
| Masa berakhir | subscription.expired |
| Perubahan pada setiap bidang | subscription.updated |
Subscription Webhook Payloads
Lihat skema payload lengkap untuk acara siklus hidup langganan.
Manajemen API
Create subscriptions
Create subscriptions
Gunakan
POST /subscriptions untuk membuat langganan secara programatis dari produk, dengan uji coba dan add-on opsional.API Reference
Lihat API pembuatan langganan.
Update subscriptions
Update subscriptions
Gunakan
PATCH /subscriptions/{id} untuk memperbarui kuantitas, membatalkan pada tanggal penagihan berikutnya, atau memodifikasi metadata.API Reference
Pelajari cara memperbarui detail langganan.
Change plans (proration)
Change plans (proration)
Ubah produk aktif dan kuantitas dengan kontrol proration.
API Reference
Tinjau opsi perubahan paket.
On‑demand charges
On‑demand charges
Untuk langganan berdasarkan permintaan, kenakan jumlah tertentu sesuai permintaan.
API Reference
Tagih langganan sesuai permintaan.
List and retrieve
List and retrieve
Gunakan
GET /subscriptions untuk menyusun daftar semua langganan dan GET /subscriptions/{id} untuk mendapatkan satu langganan.API Reference
Jelajahi API penyusunan daftar dan pengambilan.
Usage history
Usage history
Ambil penggunaan yang terukur untuk model harga metered atau hybrid.
API Reference
Lihat API riwayat penggunaan.
Update payment method
Update payment method
Perbarui metode pembayaran untuk langganan. Untuk langganan aktif, ini memperbarui metode pembayaran untuk pembaruan di masa depan. Untuk langganan dalam status
on_hold, ini mengaktifkan kembali langganan dengan membuat biaya untuk hutang yang tersisa.Ketika menghasilkan tautan metode pembayaran baru (tipe permintaan New), Anda dapat memasukkan allowed_payment_method_types untuk membatasi metode pembayaran mana yang dilihat pelanggan di halaman itu. Pelanggan tidak akan pernah melihat metode yang tidak ada dalam daftar, meskipun memasukkan metode tidak menjamin metode itu muncul (ketersediaan masih bergantung pada faktor seperti lokasi pelanggan dan pengaturan bisnis Anda).API Reference
Pelajari cara memperbarui metode pembayaran dan mengaktifkan kembali langganan.
Kasus Penggunaan Umum
- SaaS dan API: Akses bertingkat dengan add-on untuk kursi atau penggunaan
- Konten dan media: Akses bulanan dengan uji coba pengantar
- Paket dukungan B2B: Kontrak tahunan dengan add-on dukungan premium
- Alat dan plugin: Kunci lisensi dan rilis versi
Contoh Integrasi
Sesi Pembayaran (langganan)
Saat membuat sesi pembayaran, sertakan produk langganan Anda dan add-on opsional:Perubahan paket dengan proration
Upgrade atau downgrade langganan dan kontrol perilaku proration:Batalkan pada tanggal penagihan berikutnya
Jadwal pembatalan yang berlaku pada akhir periode penagihan saat ini:Langganan berdasarkan permintaan
Buat langganan berdasarkan permintaan dan tagih nanti sesuai kebutuhan:Perbarui metode pembayaran untuk langganan aktif
Perbarui metode pembayaran untuk langganan aktif:Mengaktifkan kembali langganan dari on_hold
Aktifkan kembali langganan yang dijeda karena pembayaran gagal:Langganan dengan Mandat Sesuai RBI
Langganan UPI dan kartu India beroperasi di bawah regulasi RBI (Bank Sentral India) dengan persyaratan mandat tertentu:Batas Mandat
Jenis dan jumlah mandat bergantung pada biaya berulang langganan Anda:- Biaya di bawah batas bawah mandat (default ₹15,000): Kami membuat mandat berdasarkan permintaan untuk jumlah batas bawah. Jumlah langganan dikenakan secara berkala sesuai dengan frekuensi langganan Anda, hingga batas mandat.
- Biaya di atau di atas batas bawah mandat: Kami membuat mandat langganan (atau mandat berdasarkan permintaan) untuk jumlah langganan yang tepat.
mandate_min_amount_inr_paise (INR paise). Jumlah yang didaftarkan dengan bank adalah max(mandate_floor, billing_amount) — sehingga batas bawah secara efektif menjadi batas otorisasi yang terlihat oleh pelanggan setiap kali penagihan lebih rendah.
Untuk informasi terperinci tentang mandat yang sesuai dengan RBI dan batas bawah mandat yang dapat dikonfigurasi untuk metode pembayaran India, lihat halaman India Payment Methods.
Pertimbangan Dalam Upgrade dan Downgrade
Penting: Saat melakukan upgrade atau downgrade langganan, pertimbangkan dengan cermat batas mandat:- Jika upgrade/downgrade menghasilkan jumlah biaya yang melebihi Rs 15,000 dan melampaui batas pembayaran berdasarkan permintaan yang ada, biaya transaksi mungkin gagal.
- Dalam kasus seperti itu, pelanggan mungkin perlu memperbarui metode pembayaran mereka atau mengubah langganan lagi untuk membentuk mandat baru dengan batas yang benar.
Otorisasi untuk Biaya Bernilai Tinggi
Untuk biaya langganan sebesar Rs 15,000 atau lebih:- Pelanggan akan diberitahukan oleh bank mereka untuk mengotorisasi transaksi.
- Jika pelanggan gagal mengotorisasi transaksi, transaksi akan gagal dan langganan akan dijeda.
Keterlambatan Proses 48 Jam
Garis Waktu Pemrosesan: Biaya berulang untuk langganan kartu India dan UPI mengikuti pola pemrosesan unik:- Biaya dimulai pada tanggal yang dijadwalkan sesuai dengan frekuensi langganan Anda.
- Pengurangan sebenarnya dari akun pelanggan terjadi hanya setelah 48 jam dari inisiasi pembayaran.
- Jendela 48 jam ini dapat diperpanjang hingga 2-3 jam tambahan tergantung pada respons API bank.
Jendela Pembatalan Mandat
Selama jendela pemrosesan 48 jam:- Pelanggan dapat membatalkan mandat melalui aplikasi perbankan mereka.
- Jika pelanggan membatalkan mandat selama periode ini, langganan akan tetap aktif (ini adalah kasus khusus untuk langganan kartu dan UPI AutoPay India).
- Namun, pengurangan sebenarnya mungkin gagal, dan dalam hal itu, kami akan menempatkan langganan dalam penangguhan.
- Menunda aktivasi manfaat hingga konfirmasi pembayaran
- Menerapkan masa tenggang atau akses sementara
- Memonitor status langganan untuk pembatalan mandat
- Menangani status penangguhan langganan dalam logika aplikasi Anda
Praktik Terbaik
- Mulai dengan tingkatan yang jelas: 2–3 paket dengan perbedaan yang jelas
- Komunikasikan harga: Perlihatkan total, proration, dan pembaruan berikutnya
- Gunakan uji coba dengan bijak: Konversi dengan onboarding, bukan hanya waktu
- Manfaatkan add-on: Jaga agar paket dasar tetap sederhana dan tawarkan tambahan
- Uji perubahan: Validasi perubahan paket dan proration dalam mode uji
Langganan adalah fondasi fleksibel untuk pendapatan berulang. Mulailah dengan sederhana, uji secara menyeluruh, dan iterasi berdasarkan adopsi, churn, dan metrik ekspansi.