Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Kunci lisensi adalah jenis hak Kunci Lisensi. Buat hak Kunci Lisensi sekali dengan batas aktivasi, masa berlaku, dan instruksi yang Anda inginkan, lampirkan ke produk apa pun, dan Dodo Payments menghasilkan serta mengirimkan kunci per pembelian atau kursi langganan, secara otomatis.

​
Apa itu Kunci Lisensi?

Kunci lisensi adalah token unik yang mengotorisasi akses ke produk Anda. Mereka ideal untuk:
  • Lisensi perangkat lunak: Aplikasi desktop, plugin, dan CLI
  • Kontrol per pengguna: Batasi aktivasi per pengguna atau perangkat
  • Barang digital: Batasi unduhan, pembaruan, atau fitur premium
Di dalam Dodo Payments, kunci lisensi dikelola melalui sistem Entitlements, yang berarti siklus hidup setiap kunci (pembuatan, kadaluarsa, pencabutan, pengaktifan ulang) didorong oleh peristiwa pembayaran dan langganan yang sama seperti penghantaran lainnya.

​
Buat Hak Kunci Lisensi

1

Open Entitlements

Pergi ke Entitlements di dasbor Dodo Payments Anda dan klik + untuk membuat entitlements baru.
2

Choose License Key

Pilih License Key sebagai integrasi. Konfigurasikan bagaimana setiap kunci yang diterbitkan berperilaku:
  • Activations Limit: Aktivasi bersamaan maksimum per kunci (misalnya, 1 untuk pengguna tunggal, 5 untuk lisensi tim, kosongkan untuk tidak terbatas).
  • Duration: Berapa lama kunci tetap berlaku setelah diterbitkan (misalnya, 30 hari, 1 tahun). Untuk kunci yang diterbitkan melalui langganan, kosongkan; kunci tetap berlaku selama langganan aktif.
  • Activation Instructions: Instruksi yang dikirimkan kepada pelanggan bersama dengan kunci. Contoh: Paste the key in Settings → License atau Run: mycli activate <key>.
Formulir Hak Kunci Lisensi dengan batas aktivasi, durasi, dan instruksi
3

Save the entitlement

Simpan. Hak tersebut sekarang tersedia untuk dilampirkan pada produk apa pun.

​
Lampirkan ke Produk

Buka produk, perluas Advanced Settings → Entitlements & Credits, dan pilih hak Kunci Lisensi Anda. Satu produk dapat mengirimkan kunci lisensi bersama dengan hak lain (akses Discord, unduhan file, akses repo GitHub, dll.) pada pembelian yang sama.
Panel penghargaan produk dengan Kunci Lisensi dipilih

​
Bagaimana Kunci Dibagikan

Penerbitan kunci mengikuti standar siklus hidup penghargaan:
PeristiwaPerilaku
payment.succeeded (sekali saja)Menghasilkan satu kunci per quantity yang dibeli. Kadaluarsa kunci mengikuti durasi hak.
subscription.activeMenghasilkan satu kunci per langganan quantity (kursi). Kunci tidak memiliki kadaluarsa; keabsahan terkait dengan status langganan.
subscription.renewedTidak ada operasi. Kunci yang ada tetap ada.
subscription.on_holdMenonaktifkan kunci. Kunci akan diaktifkan kembali ketika langganan tidak lagi ditahan.
subscription.cancelled / expiredMenonaktifkan kunci secara permanen.
subscription.plan_changedMenonaktifkan kunci lama; mengeluarkan kunci baru untuk rencana baru.
refund.succeeded (sekali saja)Menonaktifkan kunci.
Pencabutan manual melalui API/dasborMenonaktifkan kunci dengan revocation_reason: manual. Ini tidak akan diterbitkan kembali secara otomatis pada pembaruan langganan.
Kunci lisensi dinonaktifkan langsungMencabut penghargaan dengan revocation_reason: license_key_disabled. Mengaktifkan kembali kunci akan mengaktifkan kembali penghargaan secara otomatis.

​
Perilaku Kuantitas

  • Produk langganan menerbitkan satu kunci per kursi (subscriptions.quantity).
  • Produk satu kali mengeluarkan satu kunci per item garis keranjang (product_cart.quantity).
  • Pemberian API manual mengeluarkan tepat satu kunci.

​
Aktivasi, Validasi, Penonaktifan

Endpoint API untuk aktivasi/validasi/penonaktifan bersifat publik dan tidak memerlukan kunci API. Gunakan secara langsung dari perangkat lunak desktop, CLI, atau klien berbasis peramban untuk memverifikasi kunci pada saat menjalankan.
Public Endpoints: Aktivasi, penonaktifan, dan validasi endpoint lisensi bersifat publik dan tidak memerlukan kunci API. Panggil secara langsung dari aplikasi klien Anda tanpa mengekspos kredensial API Anda.

​
Aktivasi lisensi

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

​
Validasi lisensi

const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

​
Nonaktifkan instance aktivasi

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});

​
Mengelola Kunci

Buka hak Kunci Lisensi dari dasbor Anda untuk melihat setiap penghargaan (satu baris per kunci pelanggan) dengan tanggal pengiriman, jumlah aktivasi, dan tindakan pencabutan. Setiap detail penghargaan memunculkan kunci lisensi yang mendasari, kadaluarsa, aktivasi yang digunakan, dan batas aktivasi. Anda juga dapat membuat daftar penghargaan secara terprogram: 
const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}

​
Impor Kunci Lisensi yang Ada melalui API

Sudah memiliki kunci lisensi di sistem lain? Gunakan API Create License Key untuk mengimpornya ke Dodo Payments. Ini memungkinkan Anda memigrasikan kunci yang ada tanpa mengganggu pelanggan Anda — mereka tetap mengaktifkan, memvalidasi, dan menonaktifkan terhadap string kunci yang sama tanpa penerbitan ulang.
Kunci lisensi yang dibuat atau diperbarui melalui API tidak memberikan pemberitahuan email kepada pelanggan. Jika Anda perlu memberi tahu pelanggan tentang kunci yang diimpor, tangani secara terpisah dalam aplikasi Anda.
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'prod_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​
Perbedaan kunci impor dari kunci yang dihasilkan otomatis

BidangKunci yang dihasilkan otomatisKunci impor
source"auto""import"
payment_idDiatur ke pembayaran asalnull (tidak ada transaksi Dodo Payments)
subscription_idDiatur jika kunci diterbitkan melalui langganannull kecuali secara eksplisit terhubung
Pemberitahuan email pelangganDikirim pada penerbitanTidak dikirim — tangani secara terpisah
Gunakan bidang source di tanggapan GET /license_keys untuk membedakan inventaris yang dimigrasi dari kunci yang dikeluarkan secara organik saat merekonsiliasi atau mengaudit.
Migrasi dari Polar.sh atau Lemon Squeezy? dodo-migrate CLI mengotomatisasi impor massal produk, pelanggan, diskon, dan kunci lisensi dalam satu perintah dan memetakan ID eksternal ke ID Dodo secara otomatis.

​
Kunci Lisensi dalam URL Pengembalian

Ketika pelanggan menyelesaikan pembelian untuk produk dengan hak Kunci Lisensi, kunci yang dihasilkan secara otomatis ditambahkan ke return_url Anda sebagai parameter kueri. Ini memungkinkan Anda menampilkan kunci segera di halaman sukses Anda tanpa perlu memanggil API tambahan. 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
Jika pembelian menghasilkan beberapa kunci (kuantitas > 1), mereka dipisahkan dengan koma: 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
Untuk langganan, subscription_id digunakan sebagai pengganti payment_id: 
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
Parse parameter license_key di halaman pengembalian Anda untuk menampilkan kunci segera, meningkatkan pengalaman pasca pembelian.

​
Manajemen API

Aktivasi, penonaktifan, dan validasi bersifat publik; tidak diperlukan kunci API.

Activate License

Buat atau catat instance aktivasi untuk kunci lisensi.

Deactivate License

Mencabut aktivasi sebelumnya untuk membebaskan kapasitas.

Validate License

Periksa keaslian, status, dan batasan sebelum memberikan akses.
Buat, daftar, ambil, dan perbarui catatan kunci lisensi individual. Gunakan ini untuk mengimpor kunci yang ada atau mengambil detail penggunaan.

Create License Key

Buat kunci lisensi baru atau impor kunci yang sudah ada.

List License Keys

Telusuri semua kunci dengan status dan detail penggunaan.

Get License Key

Ambil kunci tertentu dan metadata-nya.

Update License Key

Modifikasi masa kadaluarsa, batas aktivasi, atau aktifkan/nonaktifkan kunci.
Kelola hak Kunci Lisensi itu sendiri: batas aktivasi, durasi, dan instruksinya.

Create Entitlement

Buat hak Kunci Lisensi.

Update Entitlement

Perbarui konfigurasi hak.

List Grants

Daftar kunci yang diterbitkan untuk hak tersebut.

Revoke Grant

Mencabut kunci pelanggan secara manual.

​
Webhooks

Penyampaian kunci lisensi dan pencabutan memicu empat entitlement_grant.* peristiwa webhook. Muatan penghargaan mencakup license_key objek dengan kunci, kadaluarsa, aktivasi yang digunakan, dan batas. Acara license_key.* lama (license_key.created) terus memicu untuk siklus hidup rekaman kunci lisensi yang mendasari; lihat halaman muatan webhook Kunci Lisensi.
Untuk integrasi baru, dengarkan entitlement_grant.delivered daripada license_key.created. Peristiwa hak memberitahu Anda penyampaian selesai di semua integrasi pada produk, bukan hanya kunci lisensi.

​
Kunci Lisensi Lama

Produk yang dibuat dengan bendera lama license_key_enabled telah secara otomatis dimigrasikan ke hak Kunci Lisensi. Migrasi ini transparan: kunci pelanggan yang ada tetap bekerja tanpa perubahan, public /licenses/activate, /licenses/validate, /licenses/deactivate endpoint tetap berfungsi, dan /license_keys/* endpoint API terus membaca dan menulis ke penyimpanan kunci yang sama.Bagian dasbor License Keys yang berdiri sendiri tetap tersedia sebagai daftar datar setiap kunci yang diterbitkan, berguna untuk audit dan pencarian. Konfigurasi baru (mengubah batas aktivasi, durasi, atau instruksi) harus dilakukan dengan mengedit hak Kunci Lisensi yang dimigrasikan di bawah Entitlements.

​
Praktik Terbaik

  • Simpan batas aktivasi dengan jelas: Pilih default yang masuk akal (1 untuk aplikasi pengguna tunggal, 3–5 untuk lisensi tim) dan dokumentasikan.
  • Berikan instruksi aktivasi yang tepat: Pelanggan menyalin dan menempel dari email mereka, sehingga jalur dan perintah yang tepat menghemat tiket dukungan.
  • Validasi kunci sisi server: Untuk produk yang terhubung ke jaringan, validasi melalui /licenses/validate alih-alih menyimpan aktivasi secara lokal.
  • Gunakan webhooks untuk pencabutan: Dengarkan entitlement_grant.revoked untuk menonaktifkan fitur dalam aplikasi segera ketika pelanggan membatalkan atau mengembalikan.
  • Uji dengan langganan dan satu kali: Perilaku kunci lisensi berbeda secara halus antara keduanya, jadi uji keduanya sebelum ditayangkan.
Last modified on May 14, 2026