Subscriptions - Dodo Payments Documentation

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.

Pick the most accurate tax category to ensure correct tax collection per region.

Pricing

Pricing Type: Pilih Subscription (panduan ini). Alternatifnya adalah Single Payment dan Usage Based Billing.
Price (wajib): Harga dasar berulang dengan mata uang. Harga harus sekurang-kurangnya $1 (atau setara dalam mata uang yang dipilih). Jumlah di bawah minimum ini tidak didukung dan subscription tidak akan berfungsi.
Discount Applicable (%): Diskon persentase opsional yang diterapkan pada harga dasar; tercermin di checkout dan invoice.
Repeat payment every (wajib): Interval untuk perpanjangan, misalnya setiap 1 Month. Pilih cadence (bulan atau tahun) dan jumlahnya.
Subscription Period (wajib): Jangka waktu total subscription tetap aktif (misalnya 10 Years). Setelah periode ini berakhir, perpanjangan berhenti kecuali diperpanjang.
Trial Period Days (wajib): Tetapkan durasi trial dalam hari. Gunakan 0 untuk menonaktifkan trial. Tagihan pertama dibuat secara otomatis saat trial berakhir.
Trial Amount: Biaya awal opsional untuk paid trial. Biarkan tidak diisi untuk free trial. Lihat Paid Trials.
Select add‑on: Lampirkan hingga 10 add-on yang dapat dibeli pelanggan bersama paket dasar.

Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.

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.

Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.

Subscription Trials

Trial memungkinkan pelanggan mengevaluasi subscription sebelum membayar harga berulang penuh. Trial dapat berupa free, ketika tidak ada biaya yang dikenakan hingga trial berakhir, atau paid, ketika jumlah yang lebih rendah dikenakan di muka. Dalam kedua kasus tersebut, harga penuh mulai berlaku pada perpanjangan pertama setelah trial berakhir.

Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

The trial_period_days value must be between 0 and 10,000 days.

Paid Trials

Trial tidak harus gratis. Tetapkan Trial Amount pada harga berulang produk subscription untuk mengenakan biaya awal yang lebih rendah selama jendela trial. Harga berulang penuh kemudian mulai berlaku pada perpanjangan pertama.

Subscription pricing form with a trial duration and an optional trial amount for a paid trial

Paid trial dikonfigurasi pada harga produk, bukan per subscription atau per checkout session:

Field	Type	Description
`trial_amount`	integer	Jumlah yang dikenakan hari ini untuk trial, dalam unit minor mata uang harga (misalnya, `500` untuk $5.00). Memerlukan `trial_period_days > 0`. Kosongkan atau tetapkan ke `null` untuk free trial.
`trial_apply_discounts`	boolean	Menentukan apakah kode diskon checkout mengurangi biaya trial. Default-nya `false`, sehingga jumlah trial dikenakan penuh meskipun diskon diterapkan pada harga berulang.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Paid trial juga diproses melalui checkout. Jumlah trial dikenai pajak, ditampilkan dalam perhitungan checkout session dan harga payment link, serta markup Adaptive Currency diterapkan per mata uang. Preview endpoint mengembalikan trial_amount dan trial_period_days sehingga Anda dapat menampilkan jumlah yang harus dibayar hari ini sebelum subscription dibuat.

Free trial tidak berubah. Membiarkan Trial Amount kosong akan mempertahankan perilaku yang ada, yaitu biaya pertama adalah 0 dan harga penuh dikenakan saat trial berakhir.

Mencegah Penyalahgunaan Trial

Prevent Trial Misuse mencegah pelanggan berulang kali mengklaim trial untuk bisnis yang sama. Saat diaktifkan, pelanggan yang sebelumnya telah menukarkan trial akan secara otomatis dialihkan ke paid, no-trial purchase, bukan menerima trial baru.

Prevent Trial Misuse toggle in the Subscriptions settings tab

Aktifkan dari tab Subscriptions di Settings. Setelah diaktifkan:

Pelanggan dicocokkan berdasarkan normalized email, dengan plus-alias yang dihapus, sehingga user+trial@example.com dan user@example.com dianggap sebagai orang yang sama.
Penukaran dicatat saat trial activation, sehingga pelanggan yang membatalkan pada hari yang sama tetap dianggap telah menggunakan trial mereka.
Pelanggan yang sudah ada di-backfill berdasarkan trial historis melalui email, sehingga pengguna trial sebelumnya langsung dikenali.

Pengaturan ini off by default. Lihat Subscription Settings untuk daftar lengkap kontrol subscription tingkat bisnis.

Mendeteksi Status Trial

Saat ini tidak ada field langsung untuk mendeteksi status trial. Solusi berikut memerlukan query payments, yang tidak efisien. Kami sedang mengembangkan solusi yang lebih efisien.

Untuk menentukan apakah subscription free trial sedang dalam masa trial, ambil daftar payments untuk subscription tersebut. Jika terdapat tepat satu payment dengan amount 0, subscription berada dalam masa trial:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Pemeriksaan jumlah nol ini hanya berfungsi untuk free trial. Untuk paid trial, payment pertama sama dengan jumlah trial, bukan 0. Bandingkan payment pertama dengan trial_amount milik subscription, atau periksa apakah next_billing_date masih berada dalam jendela trial.

Memperbarui Periode Trial

Perpanjang trial dengan memperbarui next_billing_date:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

Anda tidak dapat menetapkan next_billing_date ke waktu yang telah berlalu. Tanggal tersebut harus berada di masa mendatang.

Perubahan Paket Subscription

Perubahan paket memungkinkan Anda melakukan upgrade atau downgrade subscription, menyesuaikan jumlah, atau berpindah ke produk lain. Bergantung pada mode proration yang dipilih, perubahan dapat memicu biaya langsung, membuat kredit, atau tidak menerapkan penyesuaian billing.

Anda dapat mengubah paket subscription dan memperbarui tanggal billing berikutnya langsung dari dashboard Dodo Payments. Ini menyediakan cara cepat untuk menyesuaikan subscription berdasarkan permintaan dukungan pelanggan, upgrade promosi, atau migrasi paket tanpa melakukan panggilan API.

Aktifkan perubahan paket secara mandiri: Ingin pelanggan meng-upgrade atau men-downgrade subscription mereka sendiri melalui Customer Portal? Tambahkan produk subscription ke Product Collection dan aktifkan “Allow Subscription Updates” di Subscription Settings.

Product Collections

Kelompokkan produk terkait ke dalam collection untuk mengaktifkan alur upgrade/downgrade yang mulus di Customer Portal.

Mode Proration

Pilih cara pelanggan ditagih saat mengubah paket:

Perbandingan singkat empat mode proration:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade	Biaya prorata untuk sisa hari	Selisih harga penuh ditagihkan	Harga penuh paket baru ditagihkan	Tanpa biaya — langsung berpindah
Downgrade	Kredit prorata untuk sisa hari	Selisih harga penuh sebagai kredit	Tanpa kredit, biaya penuh	Tanpa kredit — langsung berpindah
Billing cycle	Di-reset ke hari ini	Di-reset ke hari ini	Di-reset ke hari ini	Tetap sama
Cocok untuk	Billing berbasis waktu yang adil	Perubahan tier sederhana	Reset billing cycle	Migrasi gratis atau perpindahan sebagai bentuk layanan

`prorated_immediately`

Mengenakan jumlah prorata berdasarkan sisa waktu dalam billing cycle saat ini. Cocok untuk billing yang adil dan memperhitungkan waktu yang belum digunakan.

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

`difference_immediately`

Menagihkan selisih harga secara langsung (upgrade) atau menambahkan kredit untuk perpanjangan mendatang (downgrade). Cocok untuk skenario upgrade/downgrade sederhana.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Kredit dari downgrade menggunakan difference_immediately terkait dengan subscription dan otomatis diterapkan pada perpanjangan mendatang. Kredit ini berbeda dari entitlement Credit-Based Billing.

Saat pelanggan melakukan downgrade dengan difference_immediately, nilai yang belum digunakan menjadi kredit yang terkait dengan subscription dan otomatis mengimbangi perpanjangan mendatang:

`full_immediately`

Menagihkan jumlah penuh paket baru secara langsung, tanpa memperhitungkan sisa waktu. Cocok untuk mereset billing cycle.

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

`do_not_bill`

Beralih ke paket baru tanpa penyesuaian billing. Tidak ada biaya proration dan tidak ada kredit — pelanggan cukup berpindah ke paket baru. Cocok untuk migrasi sebagai bentuk layanan, perpindahan ke paket gratis, atau situasi ketika Anda ingin menanggung selisih biaya.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Skenario: Pelanggan pada Basic (

30/month) melakukan upgrade ke Pro (

80/month) pada hari ke-16 dari cycle 30 hari menggunakan prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Perpanjangan berikutnya pada 15 Februari (16 Januari + 30 hari): $80.00/month.

Untuk contoh perhitungan dan kasus khusus yang lebih mendetail, lihat Upgrade & Downgrade Guide lengkap kami.

Example: Downgrade credit calculation

Skenario: Pelanggan pada Pro (

80/month) melakukan downgrade ke Starter (

20/month) menggunakan difference_immediately.

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

Kredit $60 otomatis diterapkan pada perpanjangan mendatang:

Perpanjangan 1: $20 −$ 20 (kredit) = ** $0.00** (sisa kredit$ 40)
Perpanjangan 2: $20 −$ 20 (kredit) = ** $0.00** (sisa kredit$ 20)
Perpanjangan 3: $20 −$ 20 (kredit) = $0.00 (kredit habis)
Perpanjangan 4: $20.00 (harga penuh)

Pelajari selengkapnya tentang pengelolaan kredit di Upgrade & Downgrade Guide.

Mengubah Paket dengan Add-on

Ubah add-on saat mengubah paket. Add-on disertakan dalam perhitungan proration:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

Secara default (effective_at: 'immediately'), perubahan paket memicu tagihan segera. Teruskan effective_at: 'next_billing_date' untuk menjadwalkan perubahan pada tanggal penagihan berikutnya — perubahan yang tertunda dikembalikan pada langganan sebagai scheduled_change, dan Anda dapat membatalkannya dengan Batalkan Perubahan Paket Terjadwal. Tagihan yang gagal dapat memindahkan langganan ke status on_hold, kecuali Anda meneruskan on_payment_failure: 'prevent_change', yang mempertahankan langganan pada paket saat ini hingga pembayaran berhasil. Lacak perubahan melalui event webhook subscription.plan_changed.

Melihat Pratinjau Perubahan Paket

Sebelum menerapkan perubahan paket, lihat pratinjau biaya dan subscription yang dihasilkan secara tepat:

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('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Lihat pratinjau perubahan paket sebelum menerapkannya.

Menjeda dan Melanjutkan Subscription

Menjeda akan membekukan subscription, bukan mengakhirinya. Billing berhenti, akses dicabut, dan subscription mempertahankan plan serta riwayatnya agar customer dapat melanjutkan tepat dari posisi sebelumnya. Gunakan ini sebagai alternatif retensi selain pembatalan. Buka subscription aktif apa pun di Sales → Subscriptions, lalu klik Pause subscription. Status berubah menjadi paused dan renewal berhenti sampai subscription dilanjutkan.

Apa yang Terjadi Saat Subscription Dijeda

Renewal berhenti. Tidak ada invoice yang dibuat dan tidak ada biaya renewal yang dikenakan selama subscription dijeda.
Akses langsung dicabut. Menjeda akan mencabut setiap entitlement grant yang telah diberikan maupun yang masih tertunda pada subscription, sehingga license key dinonaktifkan dan URL download digital product baru tidak lagi diterbitkan. Saat dilanjutkan, entitlement tersebut diberikan kembali, sama seperti pemulihan dari on_hold.
Jam billing dibekukan. next_billing_date dan expires_at sama-sama maju tepat selama durasi jeda, sehingga customer tetap mendapatkan waktu yang telah mereka bayar.
Tidak ada batas durasi jeda. Subscription yang dijeda akan tetap dijeda sampai seseorang melanjutkannya. Anda tidak perlu menetapkan durasi jeda sebelumnya.

Menjeda langsung mencabut akses, bukan pada akhir periode billing. Jika subscription membatasi akses ke produk Anda, jelaskan hal ini kepada customer sebelum mereka mengonfirmasi.

Melanjutkan akan mengembalikan subscription ke active dan memulihkan entitlement-nya. Karena jam billing dibekukan, renewal berikutnya terjadi setelah durasi jeda berlalu dari jadwal semula — subscription yang dijeda selama 12 hari akan diperpanjang 12 hari lebih lambat.

Menjeda Subscription Berbasis Usage

Subscription berbasis usage dapat memiliki usage yang sudah tercatat tetapi belum ditagihkan saat dijeda. Bill Usage at Pause di Settings → Subscriptions menentukan apa yang terjadi pada usage tersebut:

Setting	Behavior
On (default)	Dodo Payments membuat invoice untuk usage yang terakumulasi sejak tanggal billing terakhir dan langsung menagihnya.
Off	Usage yang belum dibayar dibawa ke depan dan ditagihkan pada invoice reguler subscription berikutnya.

Hanya usage terukur yang diselesaikan dengan cara ini — biaya dasar berulang tidak pernah ditagihkan saat jeda. Subscription standar dan on-demand tidak memiliki saldo yang perlu diselesaikan, sehingga setting ini tidak memengaruhi keduanya.

Bill Usage at Pause dicatat per billing cycle. Mengubahnya di tengah cycle tidak mengubah cara cycle yang sedang berlangsung diselesaikan; nilai baru berlaku mulai cycle berikutnya.

Invoice penyelesaian ditagihkan seperti invoice lainnya, sehingga dapat gagal. Jika tetap belum dibayar setelah masa tenggang dunning, subscription berpindah ke on_hold dan tetap ditandai sebagai dijeda.

Subscription dalam kondisi tersebut memiliki dua cara untuk keluar, dan keduanya berbeda dalam hal pihak yang menanggung usage yang belum dibayar:

Exit	Result
Invoice penyelesaian dibayar	Subscription kembali ke `paused`, bukan `active`. Lanjutkan secara eksplisit saat customer siap.
Anda langsung melanjutkannya	Subscription langsung berpindah ke `active` dan invoice penyelesaian yang belum dibayar akan dibatalkan, bersama retry yang masih tertunda. Usage yang belum dibayar akan dihapuskan.

Melanjutkan adalah cara keluar yang valid dari penangguhan ini — Anda tidak harus menagih invoice penyelesaian terlebih dahulu. Namun, perlu diketahui bahwa melanjutkan akan menghapuskan usage yang belum dibayar, bukan menundanya.

Memungkinkan Customer Menjeda Subscription Mereka Sendiri

Allow Subscription Pause di Settings → Subscriptions mengatur apakah customer dapat menjeda dan melanjutkan dari Customer Portal. Fitur ini nonaktif secara default, sehingga jeda mandiri harus diaktifkan secara opt-in.

Setting ini hanya mengatur Customer Portal. Anda selalu dapat menjeda dan melanjutkan dari dashboard atau API, terlepas dari posisi toggle. Menonaktifkannya akan menghentikan jeda baru yang dilakukan customer, tetapi tidak mengunci customer yang sudah dijeda — mereka tetap dapat melanjutkan jeda yang mereka mulai sendiri. Jeda yang Anda mulai tetap berada dalam kendali Anda.

Pausing from the Customer Portal

Lihat tampilan yang dilihat customer, termasuk dialog konfirmasi.

Menjeda melalui API

Jeda dan lanjut adalah satu field pause pada endpoint update subscription. Tidak ada endpoint jeda terpisah.

// Pause
await client.subscriptions.update('sub_123', { pause: true });

// Resume
await client.subscriptions.update('sub_123', { pause: false });

pause bersifat eksklusif terhadap setiap field lain — mengirimkannya bersama field lain akan ditolak dengan 422. Menetapkan status ke paused tidak akan menjeda subscription; gunakan field pause.

Menjeda menghasilkan subscription.paused dan melanjutkan menghasilkan subscription.unpaused. Keduanya membawa objek subscription lengkap, dengan paused_at ditetapkan saat dijeda dan null setelah dilanjutkan.

Jeda dan Tindakan Subscription Lainnya

Pembatalan tetap berfungsi. Anda dapat membatalkan subscription yang dijeda sama seperti subscription aktif. Invoice penyelesaian yang masih terbuka dari jeda akan dibatalkan saat Anda melakukannya.
Perubahan plan terjadwal ditunda, bukan dihapus. Perubahan plan yang dijadwalkan pada tanggal billing berikutnya tetap tidak berubah saat subscription dijeda, lalu diterapkan pada tanggal billing yang bergeser setelah subscription dilanjutkan. scheduled_change.effective_at adalah snapshot saat perubahan dijadwalkan dan tidak disesuaikan dengan jeda, sehingga dapat menampilkan tanggal yang sudah lewat — bacalah sebagai “dijadwalkan untuk”, bukan sebagai tanggal yang dijamin. Untuk menghapus perubahan tersebut, gunakan Cancel Scheduled Plan Change.

Status Subscription

Subscription berpindah melalui serangkaian status yang telah ditentukan sepanjang masa berlakunya. Tabel ini menjadi referensi untuk setiap status, penyebabnya, serta cara (atau apakah) status tersebut dapat dipulihkan.

Status	What it means	Recoverable?	Recovery path / next step
`pending`	Subscription sedang dibuat atau diproses	—	Tunggu `subscription.active` (atau `subscription.failed`)
`active`	Subscription aktif dan akan diperpanjang otomatis	—	Tidak diperlukan tindakan
`on_hold`	Pembayaran renewal (atau biaya perubahan plan) gagal; renewal berhenti	Ya	Perbarui metode pembayaran untuk mengaktifkannya kembali — otomatis melalui Payment Retries dan Dunning, atau secara manual melalui Update Payment Method API
`paused`	Subscription sengaja dijeda oleh Anda atau customer; billing dibekukan dan akses dicabut	Ya	Lanjutkan dengan `pause: false`, atau dari Customer Portal jika jeda mandiri diaktifkan — lihat Menjeda dan Melanjutkan Subscription
`cancelled`	Subscription dibatalkan dan tidak akan diperpanjang	Hanya dapat dibeli ulang	Customer harus memulai subscription baru; Dunning dapat mendorong pembelian ulang
`failed`	Pembuatan subscription gagal (mandate atau pembayaran awal tidak berhasil)	Tidak — terminal	Customer harus membuat subscription baru dengan metode pembayaran yang berfungsi
`expired`	Subscription mencapai akhir masa berlakunya	—	Customer harus memulai subscription baru jika diinginkan

on_hold dan failed sering tertukar. on_hold adalah status yang dapat dipulihkan untuk subscription yang sudah aktif tetapi renewal-nya gagal. failed adalah status terminal yang hanya terjadi saat pembuatan awal subscription gagal — status ini tidak dapat diaktifkan kembali.

on_hold dan paused juga berbeda. on_hold bersifat tidak disengaja — pembayaran gagal. paused disengaja — Anda atau customer memilih untuk membekukan subscription, dan tidak ada renewal yang dicoba selama subscription tetap dijeda. Subscription berbasis usage masih dapat memiliki invoice penyelesaian satu kali yang harus dibayar saat dijeda; lihat Menjeda Subscription Berbasis Usage.

State Machine

Status On Hold

Subscription memasuki status on_hold ketika:

Pembayaran renewal gagal (saldo tidak cukup, kartu kedaluwarsa, dan sebagainya)
Biaya perubahan plan gagal
Otorisasi metode pembayaran gagal
Invoice penyelesaian jeda untuk subscription berbasis usage tidak dibayar

Saat subscription berada dalam status on_hold, subscription tidak akan diperpanjang otomatis. Anda harus memperbarui metode pembayaran untuk mengaktifkannya kembali.

Mengaktifkan Kembali dari On Hold

Untuk mengaktifkan kembali subscription dari status on_hold, perbarui metode pembayaran. Proses ini secara otomatis:

Membuat charge untuk tagihan yang tersisa
Membuat invoice
Memproses pembayaran menggunakan metode pembayaran baru
Mengaktifkan kembali subscription ke status active setelah pembayaran berhasil

Satu-satunya pengecualian adalah status hold yang disebabkan oleh invoice penyelesaian jeda yang belum dibayar. Melunasi invoice tersebut mengembalikan subscription ke paused, bukan active, karena jeda adalah status sebelum pembayaran gagal. Lanjutkan secara eksplisit setelah invoice diselesaikan.

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Setelah berhasil memperbarui metode pembayaran untuk subscription on_hold, Anda akan menerima event webhook payment.succeeded, kemudian subscription.active.

Event Webhook berdasarkan Transisi

Setiap transisi menghasilkan webhook sehingga Anda dapat menjalankan logika entitlement tanpa polling:

Transition	Event
Subscription diaktifkan	`subscription.active`
Renewal berhasil	`subscription.renewed`
Renewal gagal → on hold	`subscription.on_hold`
Subscription dijeda	`subscription.paused`
Subscription yang dijeda dilanjutkan	`subscription.unpaused`
Pembuatan gagal	`subscription.failed`
Plan di-upgrade/downgrade	`subscription.plan_changed`
Dibatalkan	`subscription.cancelled`
Masa berlaku berakhir	`subscription.expired`
Perubahan field apa pun	`subscription.updated`

Subscription Webhook Payloads

Lihat skema payload lengkap untuk event lifecycle subscription.

Manajemen API

Create subscriptions

Gunakan POST /checkouts untuk membuat subscription secara programatis dari product, dengan trial opsional (subscription_data.trial_period_days) dan add-on (product_cart[].addons).

POST /subscriptions sudah deprecated. Integrasi yang ada tetap berfungsi, tetapi integrasi baru sebaiknya menggunakan Checkout Sessions.

API Reference

Lihat API untuk membuat checkout session.

Update subscriptions

Gunakan PATCH /subscriptions/{subscription_id} untuk membatalkan pada tanggal billing berikutnya, memperpanjang periode subscription, memperbarui detail billing, atau mengubah metadata. Untuk mengubah quantity, gunakan Change Plan API — PATCH tidak menerima quantity.

API Reference

Pelajari cara memperbarui detail subscription.

Pause and resume subscriptions

Jeda dan lanjut menggunakan endpoint PATCH /subscriptions/{subscription_id} yang sama dengan field pause: pause: true menjeda subscription aktif dan pause: false melanjutkannya. Field ini tidak dapat digabungkan dengan field lain dalam request yang sama. Untuk perilaku lengkap, dampak billing, dan pengaturan bisnis terkait, lihat Menjeda dan Melanjutkan Subscription.

API Reference

Lihat API update subscription, termasuk field pause.

Change plans (proration)

Ubah product aktif dan quantity dengan kontrol proration.

API Reference

Tinjau opsi perubahan plan.

On‑demand charges

Untuk subscription on-demand, kenakan jumlah tertentu sesuai kebutuhan.

API Reference

Kenakan biaya pada subscription on-demand.

List and retrieve

Gunakan GET /subscriptions untuk mencantumkan semua subscription dan GET /subscriptions/{id} untuk mengambil satu subscription.

API Reference

Jelajahi API untuk pencantuman dan pengambilan data.

Usage history

Ambil usage yang tercatat untuk model pricing terukur atau hybrid.

API Reference

Lihat API riwayat usage.

Update payment method

Perbarui metode pembayaran untuk subscription. Untuk subscription aktif, ini memperbarui metode pembayaran untuk renewal mendatang. Untuk subscription dalam status on_hold, ini mengaktifkan kembali subscription dengan membuat charge untuk tagihan yang tersisa.Saat membuat link metode pembayaran baru (jenis request New), Anda dapat meneruskan allowed_payment_method_types untuk membatasi metode pembayaran yang dilihat customer di halaman tersebut. Customer tidak akan pernah melihat metode yang tidak ada dalam daftar, meskipun penyertaan suatu metode tidak menjamin metode tersebut muncul (ketersediaannya tetap bergantung pada faktor seperti lokasi customer dan pengaturan bisnis Anda).

API Reference

Pelajari cara memperbarui metode pembayaran dan mengaktifkan kembali subscription.

Kasus Penggunaan Umum

SaaS dan API: Akses bertingkat dengan add-on untuk seat atau usage
Content dan media: Akses bulanan dengan trial pengenalan
Plan dukungan B2B: Kontrak tahunan dengan add-on dukungan premium
Tools dan plugin: License key dan rilis berversi

Contoh Integrasi

Checkout Sessions (subscription)

Saat membuat checkout session, sertakan product subscription dan add-on opsional:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ]
});

Perubahan plan dengan proration

Upgrade atau downgrade subscription dan kendalikan perilaku proration:

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

Membatalkan pada tanggal billing berikutnya

Jadwalkan pembatalan yang berlaku pada akhir periode billing saat ini:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

Memperpanjang periode subscription

Perpanjang durasi subscription dengan meneruskan subscription_period_count dan subscription_period_interval ke PATCH /subscriptions/{subscription_id}. Masa berlaku subscription dihitung ulang berdasarkan count dan interval baru — misalnya, untuk memberikan waktu tambahan kepada customer pada plan mereka saat ini:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

Periode subscription hanya dapat diperpanjang, tidak dapat dipersingkat.

Subscription on-demand

Buat subscription on-demand dan kenakan biaya nanti sesuai kebutuhan:

const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Memperbarui metode pembayaran untuk subscription aktif

Perbarui metode pembayaran untuk subscription aktif:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

Mengaktifkan kembali subscription dari on_hold

Aktifkan kembali subscription yang masuk status on hold karena pembayaran gagal:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Subscription dengan Mandate yang Mematuhi RBI

Subscription UPI dan kartu India beroperasi berdasarkan regulasi RBI (Reserve Bank of India) dengan persyaratan mandate tertentu:

Batas Mandate

Jenis dan jumlah mandate bergantung pada charge berulang subscription Anda:

Charge di bawah batas minimum mandate (default ₹15,000): Kami membuat mandate on-demand sebesar batas minimum tersebut. Jumlah subscription ditagihkan secara berkala sesuai frekuensi subscription, hingga batas mandate.
Charge pada atau di atas batas minimum mandate: Kami membuat mandate subscription (atau mandate on-demand) sebesar jumlah subscription yang tepat.

Batas minimum mandate dapat dikonfigurasi per merchant atau per request melalui mandate_min_amount_inr_paise (paise INR). Jumlah yang didaftarkan ke bank adalah max(mandate_floor, billing_amount) — sehingga batas minimum tersebut secara efektif menjadi batas otorisasi yang dilihat customer setiap kali billing lebih rendah. Untuk informasi terperinci tentang mandate yang mematuhi RBI dan batas minimum mandate yang dapat dikonfigurasi untuk metode pembayaran India, lihat halaman India Payment Methods.

Pertimbangan Upgrade dan Downgrade

Penting: Saat melakukan upgrade atau downgrade subscription, pertimbangkan batas mandate dengan cermat:

Jika upgrade/downgrade menghasilkan jumlah charge yang melebihi Rs 15,000 dan melampaui batas pembayaran on-demand yang ada, charge transaksi dapat gagal.
Dalam kasus tersebut, customer mungkin perlu memperbarui metode pembayaran atau mengubah subscription lagi untuk membuat mandate baru dengan batas yang sesuai.

Otorisasi untuk Charge Bernilai Tinggi

Untuk charge subscription sebesar Rs 15,000 atau lebih:

Bank customer akan meminta mereka mengotorisasi transaksi.
Jika customer gagal mengotorisasi transaksi, transaksi akan gagal dan subscription akan masuk status on hold.

Penundaan Pemrosesan 48 Jam

Linimasa Pemrosesan: Charge berulang pada kartu India dan subscription UPI mengikuti pola pemrosesan khusus:

Charge dimulai pada tanggal yang dijadwalkan sesuai frekuensi subscription Anda.
Pemotongan aktual dari rekening customer hanya terjadi setelah 48 jam sejak pembayaran dimulai.
Jendela 48 jam ini dapat bertambah hingga 2–3 jam tambahan bergantung pada respons API bank.

Jendela Pembatalan Mandate

Selama jendela pemrosesan 48 jam:

Customer dapat membatalkan mandate melalui aplikasi perbankan mereka.
Jika customer membatalkan mandate selama periode ini, subscription akan tetap active (ini adalah kasus khusus untuk subscription Indian card dan UPI AutoPay).
Namun, pemotongan aktual dapat gagal, dan dalam kasus tersebut kami akan menempatkan subscription dalam status on hold.

Penanganan Kasus Khusus: Jika Anda memberikan manfaat, kredit, atau akses penggunaan subscription kepada customer segera setelah charge dimulai, Anda perlu menangani jendela 48 jam ini dengan tepat dalam aplikasi. Pertimbangkan:

Menunda aktivasi manfaat hingga pembayaran dikonfirmasi
Menerapkan masa tenggang atau akses sementara
Memantau status subscription untuk pembatalan mandate
Menangani status hold subscription dalam logika aplikasi Anda

Pantau webhook subscription untuk melacak perubahan status pembayaran dan menangani kasus khusus ketika mandate dibatalkan selama jendela 48 jam.

Praktik Terbaik

Mulai dengan tier yang jelas: 2–3 plan dengan perbedaan yang mudah dipahami
Komunikasikan pricing: Tampilkan total, proration, dan renewal berikutnya
Gunakan trial dengan bijak: Lakukan konversi melalui onboarding, bukan hanya waktu
Manfaatkan add-on: Buat plan dasar tetap sederhana dan tawarkan tambahan
Uji perubahan: Validasi perubahan plan dan proration dalam test mode

Subscription adalah fondasi fleksibel untuk pendapatan berulang. Mulailah dengan sederhana, lakukan pengujian menyeluruh, lalu iterasikan berdasarkan metrik adopsi, churn, dan ekspansi.

Terakhir diubah pada 21 Agustus 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Paid Trials

​Mencegah Penyalahgunaan Trial

​Mendeteksi Status Trial

​Memperbarui Periode Trial

​Perubahan Paket Subscription

Product Collections

​Mode Proration

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Mengubah Paket dengan Add-on

​Melihat Pratinjau Perubahan Paket

Preview Change Plan API

​Menjeda dan Melanjutkan Subscription

​Apa yang Terjadi Saat Subscription Dijeda

​Menjeda Subscription Berbasis Usage

​Memungkinkan Customer Menjeda Subscription Mereka Sendiri

Pausing from the Customer Portal

​Menjeda melalui API

​Jeda dan Tindakan Subscription Lainnya

​Status Subscription

​State Machine

​Status On Hold

​Mengaktifkan Kembali dari On Hold

​Event Webhook berdasarkan Transisi

Subscription Webhook Payloads

​Manajemen API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Kasus Penggunaan Umum

​Contoh Integrasi

​Checkout Sessions (subscription)

​Perubahan plan dengan proration

​Membatalkan pada tanggal billing berikutnya

​Memperpanjang periode subscription

​Subscription on-demand

​Memperbarui metode pembayaran untuk subscription aktif

​Mengaktifkan kembali subscription dari on_hold

​Subscription dengan Mandate yang Mematuhi RBI

​Batas Mandate

​Pertimbangan Upgrade dan Downgrade

​Otorisasi untuk Charge Bernilai Tinggi

​Penundaan Pemrosesan 48 Jam

​Jendela Pembatalan Mandate

​Praktik Terbaik

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Paid Trials

Mencegah Penyalahgunaan Trial

Mendeteksi Status Trial

Memperbarui Periode Trial

Perubahan Paket Subscription

Mode Proration

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Mengubah Paket dengan Add-on

Melihat Pratinjau Perubahan Paket

Menjeda dan Melanjutkan Subscription

Apa yang Terjadi Saat Subscription Dijeda

Menjeda Subscription Berbasis Usage

Memungkinkan Customer Menjeda Subscription Mereka Sendiri

Menjeda melalui API

Jeda dan Tindakan Subscription Lainnya

Status Subscription

State Machine

Status On Hold

Mengaktifkan Kembali dari On Hold

Event Webhook berdasarkan Transisi

Manajemen API

Kasus Penggunaan Umum

Contoh Integrasi

Checkout Sessions (subscription)

Perubahan plan dengan proration

Membatalkan pada tanggal billing berikutnya

Memperpanjang periode subscription

Subscription on-demand

Memperbarui metode pembayaran untuk subscription aktif

Mengaktifkan kembali subscription dari on_hold

Subscription dengan Mandate yang Mematuhi RBI

Batas Mandate

Pertimbangan Upgrade dan Downgrade

Otorisasi untuk Charge Bernilai Tinggi

Penundaan Pemrosesan 48 Jam

Jendela Pembatalan Mandate

Praktik Terbaik