License Keys

License key adalah jenis entitlement License Key. Buat entitlement License Key satu kali dengan batas aktivasi, masa berlaku, dan pesan aktivasi yang Anda inginkan, lalu lampirkan ke produk apa pun. Secara default, Dodo Payments membuat dan mengirim melalui email satu key untuk setiap unit yang dibeli atau setiap seat subscription.

Apa Itu License Key?

License key adalah token unik yang mengizinkan akses ke produk Anda. Gunakan license key untuk:

Lisensi software: aplikasi desktop, plugin, dan CLI.
Kontrol per-seat: membatasi aktivasi per pengguna atau perangkat.
Produk digital: membatasi akses ke download, pembaruan, atau fitur premium.

Dodo Payments mengelola license key melalui Entitlements. Event payment dan subscription yang sama yang menggerakkan entitlement lainnya juga menggerakkan lifecycle setiap key: pembuatan, kedaluwarsa, pencabutan, dan pemberian ulang.

Create a License Key Entitlement

Open Entitlements

Buka Entitlements di dashboard dan klik + untuk membuat entitlement.

Choose License Key

Pilih License Keys, masukkan Name, lalu konfigurasikan perilaku setiap key yang diterbitkan:

Fulfillment Mode: Automatic (default) membuat dan mengirim setiap key melalui email. Manual memungkinkan Anda memasok setiap key sendiri. Lihat Manual Fulfillment.
Activations Limit: jumlah maksimum aktivasi aktif per key, misalnya 1 untuk satu pengguna atau 5 untuk lisensi tim. Pilih Unlimited tanpa batas.
License Length: berapa lama key tetap valid setelah diterbitkan, misalnya 30 hari atau 1 tahun, atau No expiration. Untuk produk subscription, pilih No expiration: key yang diterbitkan untuk subscription tidak memiliki masa kedaluwarsa, dan validitasnya mengikuti status subscription.
Activation Message: instruksi opsional yang ditujukan kepada customer, hingga 2.500 karakter, yang disertakan dalam email pengiriman key. Contoh: Paste the key in Settings → License atau Run: mycli activate <key>.

New License Key entitlement form with name, fulfillment mode, license length, activations limit, and activation message

Save the Entitlement

Klik Create Entitlement. Kini Anda dapat melampirkan entitlement ke produk apa pun.

Attach to Products

Buka produk, buka bagian Entitlements, lalu pilih entitlement License Key Anda. Satu produk dapat mengirimkan license key bersama entitlement lain dalam pembelian yang sama, seperti akses Discord, download file, atau akses repository GitHub.

Product entitlements panel with License Key selected — Selecting the License Key entitlement in the product entitlements panel.

How Keys Are Issued

Penerbitan key mengikuti grant lifecycle standar. Setiap event memengaruhi license key sebagai berikut:

Event	Perilaku
`payment.succeeded` (one-time)	Membuat satu key untuk setiap unit `quantity` yang dibeli. Masa berlaku setiap key mengikuti License Length entitlement.
`subscription.active`	Membuat satu key untuk setiap seat subscription (`quantity`). Key tidak memiliki masa kedaluwarsa. Validitasnya mengikuti status subscription.
`subscription.renewed`	Tidak ada perubahan. Key yang ada tetap aktif.
`subscription.past_due`	Tidak ada perubahan. Key tetap aktif selama grace period penuh.
`subscription.on_hold`	Menonaktifkan key. Key diaktifkan kembali ketika subscription keluar dari hold.
`subscription.paused`	Menonaktifkan key. Key diaktifkan kembali ketika subscription dilanjutkan.
`subscription.cancelled` / `expired`	Menonaktifkan key secara permanen.
`subscription.plan_changed`	Menonaktifkan key lama dan menerbitkan key baru untuk plan baru.
`refund.succeeded` (one-time)	Menonaktifkan key.
Manual revoke through the API or dashboard	Menonaktifkan key dengan `revocation_reason: manual`. Key ini tidak diberikan kembali secara otomatis saat subscription diperbarui.
License key disabled directly	Mencabut grant dengan `revocation_reason: license_key_disabled`. Mengaktifkan kembali key akan memulihkan grant secara otomatis.

Perilaku Quantity

Jumlah key bergantung pada sumber grant. Setiap key memiliki grant sendiri.

Produk subscription menerbitkan satu key per seat (subscriptions.quantity).
Produk one-time menerbitkan satu key per unit cart line item (product_cart.quantity).
Grant API manual menerbitkan tepat satu key.

Fulfillment Mode

Setiap entitlement License Key memiliki fulfillment_mode yang menentukan pihak yang memasok key:

auto (default, Automatic di dashboard): Dodo Payments membuat dan mengirim key melalui email saat payment atau subscription. Ini adalah perilaku pada tabel di atas dan berlaku ketika fulfillment_mode tidak disertakan.
manual (Manual di dashboard): setiap unit yang dibeli membuat grant Pending tanpa key, dan Anda memasok setiap nilai key. Lihat Manual Fulfillment.

Manual Fulfillment

Dengan manual fulfillment, Anda memasok setiap license key alih-alih Dodo Payments yang membuatnya. Pembelian membuat grant Pending tanpa key, memberi tahu Anda melalui webhook, dan menunggu Anda mengirimkan nilai key. Gunakan ini ketika key berasal dari sistem Anda sendiri, vendor pihak ketiga, atau kumpulan kode pre-printed yang jumlahnya terbatas.

Untuk panduan langkah demi langkah, mulai dari pembuatan produk hingga pengiriman key, lihat Manual License Key Fulfillment Integration Guide.

Kapan Menggunakannya

Automatic fulfillment sesuai untuk sebagian besar lisensi software. Pilih manual fulfillment ketika Dodo Payments tidak dapat membuat key sendiri:

Gunakan key Anda sendiri: aplikasi, produk desktop, atau license server Anda sendiri yang membuat key.
Vendor pihak ketiga: Anda menjual kembali key yang diterbitkan provider upstream, seperti game key, kredensial API, atau lisensi platform partner.
Inventaris terbatas: Anda membagikan kode dari kumpulan yang telah dialokasikan dan menetapkannya satu per satu.
Peninjauan manual: Anda ingin memeriksa pembelian sebelum memberikan akses.

Mengaktifkan Manual Fulfillment

Untuk mengaktifkan manual fulfillment melalui API, tetapkan fulfillment_mode: "manual" di integration_config entitlement License Key. Di dashboard, tetapkan Fulfillment Mode ke Manual.

// `client` is a DodoPayments instance created with your API key.
const entitlement = await client.entitlements.create({
  name: 'Pro License (Manual)',
  integration_type: 'license_key',
  integration_config: {
    fulfillment_mode: 'manual',
    activations_limit: 5,
    duration_count: 1,
    duration_interval: 'Year',
  },
});

curl -X POST https://test.dodopayments.com/entitlements \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro License (Manual)",
    "integration_type": "license_key",
    "integration_config": {
      "fulfillment_mode": "manual",
      "activations_limit": 5,
      "duration_count": 1,
      "duration_interval": "Year"
    }
  }'

fulfillment_mode kompatibel dengan versi sebelumnya. Entitlement yang dibuat sebelum pengaturan ini tersedia tidak memiliki fulfillment_mode dan berperilaku sebagai auto. Peralihan ke manual hanya memengaruhi grant yang dibuat setelah perubahan. Key yang sudah dikirim tidak berubah.

Menemukan Grant yang Menunggu Fulfillment

Saat customer membeli produk dengan entitlement mode manual, Dodo Payments membuat grant dalam status Pending tanpa key dan mengirim webhook entitlement_grant.created dengan integration_type: "license_key" dan status: "Pending". Tanggapi webhook tersebut, atau lakukan polling pada endpoint List Customer Grants dengan filter integration_type dan status:

const pending = await client.customers.listEntitlementGrants('cus_abc123', {
  integration_type: 'license_key',
  status: 'Pending',
});

Mengirimkan Key

Untuk mengirimkan key, kirim key ke endpoint Fulfill License Key Grant. Grant berpindah ke Delivered, dan Dodo Payments mengirim key melalui email kepada customer. Emailnya sama dengan yang diterima customer dalam automatic fulfillment.

cURL

curl -X POST https://test.dodopayments.com/grants/entg_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'

activations_limit dan expires_at bersifat opsional. Jika tidak disertakan, Dodo Payments menggunakan konfigurasi entitlement. Setiap grant hanya dapat dipenuhi satu kali: mencoba ulang grant yang sudah dipenuhi akan mengembalikan 409 alih-alih menerbitkan key kedua.

Anda tidak perlu mengirim key melalui email sendiri. Dodo Payments mengirimkannya ketika grant dipenuhi. Importing keys dengan POST /license_keys bekerja secara berbeda: proses ini tidak memberi tahu customer.

Aktivasi, Validasi, Deaktivasi

Software Anda mengelola key saat runtime melalui tiga endpoint. Aktivasi mencatat perangkat atau instalasi terhadap key, validasi memeriksa apakah key dapat digunakan, dan deaktivasi membebaskan sebuah aktivasi.

Public Endpoints: Endpoint activate, deactivate, dan validate license bersifat public dan tidak memerlukan API key. Panggil endpoint tersebut langsung dari software desktop, CLI, atau client berbasis browser tanpa mengekspos kredensial API Anda. Konstruktor SDK tetap memerlukan nilai bearer token, sehingga contoh SDK menggunakan placeholder.

Mengaktifkan License

Aktivasi membuat activation instance untuk key dan mengembalikannya dengan ID lki_. Simpan ID tersebut karena Anda membutuhkannya untuk menonaktifkan instance. Request mengembalikan 403 jika key tidak aktif, 404 jika key tidak ada, dan 422 jika key telah mencapai batas aktivasinya.

import DodoPayments from 'dodopayments';

// The license endpoints don't check the token, but the SDK requires a value.
// Never ship your secret API key in client software.
const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' });

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

console.log(response.id);

from dodopayments import DodoPayments

# The license endpoints don't check the token, but the SDK requires a value.
client = DodoPayments(bearer_token="public", environment="test_mode")

response = client.licenses.activate(
    license_key="PRO-AAAA-BBBB-CCCC-DDDD",
    name="Device Name",
)
print(response.id)

curl -X POST https://test.dodopayments.com/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "name": "Device Name"
  }'

Memvalidasi License

Validasi mengembalikan valid: true ketika status key adalah active dan key belum kedaluwarsa. Untuk sekaligus memeriksa apakah activation instance tertentu masih ada, kirim license_key_instance_id.

// Uses the client from the activation example.
const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

curl -X POST https://test.dodopayments.com/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'

Menonaktifkan Activation Instance

Deaktivasi menghapus activation instance dan membebaskan satu aktivasi pada key. Kirim key dan instance ID yang dikembalikan oleh aktivasi. Request mengembalikan 403 jika instance bukan milik key tersebut, dan 404 jika key tidak ada.

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

Mengelola Key

Untuk melihat key yang diterbitkan, buka entitlement License Key di bawah Entitlements. Daftar grant menampilkan satu baris untuk setiap key customer, dengan customer, tanggal akses, status, dan tindakan Revoke. Untuk melihat masa kedaluwarsa, jumlah aktivasi, dan batas aktivasi key, buka key tersebut di Sales → License Keys. Untuk membuat daftar grant secara programatis, panggil List Grants. Pada setiap grant license key, objek license_key memuat key, status, masa kedaluwarsa, aktivasi yang digunakan, dan batas aktivasi. Objek tersebut bernilai null pada grant mode manual yang masih berstatus Pending.

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);
}

Mengimpor License Key yang Ada melalui API

Untuk memigrasikan license key dari sistem lain, impor key tersebut dengan API Create License Key. Customer Anda tetap mengaktifkan, memvalidasi, dan menonaktifkan string key yang sama, sehingga Anda tidak perlu menerbitkan ulang key.

License key yang dibuat atau diperbarui melalui API tidak memicu notifikasi email kepada customer. Untuk memberi tahu customer tentang key yang diimpor, kirim notifikasi dari aplikasi Anda sendiri.

Request memerlukan key, customer_id, dan product_id. Hilangkan activations_limit untuk aktivasi tanpa batas, dan hilangkan expires_at untuk key yang tidak pernah kedaluwarsa. Mengimpor string key yang sudah ada akan mengembalikan 409.

const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

Perbedaan Key Berdasarkan Sumber

Field source mencatat cara setiap license key dibuat:

Field	Key yang dibuat otomatis	Key yang dipenuhi secara manual	Key yang diimpor
`source`	`"auto"`	`"manual"`	`"import"`
Origin	Dibuat oleh Dodo Payments saat payment	Disediakan oleh Anda untuk grant yang tertunda	Dibuat atau dimigrasikan dengan `POST /license_keys`
`payment_id`	Payment asal	Diperoleh dari grant atau subscription-nya	`null` (tidak ada transaksi Dodo Payments)
`subscription_id`	Diatur jika diterbitkan melalui subscription	Diatur jika grant berasal dari subscription	`null` (import request tidak memiliki field subscription)
Notifikasi email customer	Dikirim saat penerbitan	Dikirim saat fulfillment	Tidak dikirim. Beri tahu customer sendiri

Gunakan source untuk membedakan key yang dimigrasikan dan dipenuhi secara manual dari key yang dibuat oleh Dodo Payments, misalnya saat merekonsiliasi atau mengaudit key. Field ini terdapat pada record license key, seperti response POST /license_keys. Objek license_key pada grant dari List Grants tidak menyertakannya. Endpoint lama GET /license_keys, yang mengembalikan source dan menerima filter source, sudah deprecated.

Bermigrasi dari Polar.sh atau Lemon Squeezy? dodo-migrate CLI mengimpor produk, customer, diskon, dan license key secara massal dengan satu command, serta memetakan external ID ke ID Dodo Payments.

License Key dalam Return URL

Ketika customer membeli produk dengan entitlement License Key, Dodo Payments menambahkan key yang dibuat ke return_url Anda sebagai query parameter license_key. Success page Anda dapat menampilkan key tanpa API call tambahan:

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

Jika pembelian membuat lebih dari satu key (quantity di atas 1), parameter berisi daftar yang dipisahkan koma. Koma di-URL-encode sebagai %2C, jadi baca parameter dengan URL parser yang mendekodenya sebelum memisahkan nilainya:

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001%2CLK-002&email=customer%40example.com

Untuk subscription, URL membawa subscription_id dan status subscription, bukan payment_id:

https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com

Baca parameter license_key di return page Anda untuk menampilkan key segera setelah pembelian.

Manajemen API

Lifecycle Operations (Public Endpoints)

Aktivasi, deaktivasi, dan validasi bersifat public dan tidak memerlukan API key.

Activate License

Buat activation instance untuk license key.

Deactivate License

Hapus activation instance untuk membebaskan kapasitas.

Validate License

Pastikan key aktif dan belum kedaluwarsa sebelum memberikan akses.

License Key Management

Buat, tampilkan, ambil, dan perbarui record license key individual. Gunakan endpoint ini untuk mengimpor key yang ada atau membaca detail penggunaan.

GET /license_keys, GET /license_keys/{id}, dan PATCH /license_keys/{id} sudah deprecated. Untuk read, gunakan endpoint entitlement grant (List Grants, List Customer Grants). POST /license_keys tetap didukung untuk mengimpor key yang ada.

Create License Key

Buat license key atau impor key yang ada.

List License Keys

Telusuri semua key dengan detail status dan penggunaan.

Get License Key

Ambil key tertentu beserta metadatanya.

Update License Key

Ubah masa kedaluwarsa atau batas aktivasi, atau aktifkan maupun nonaktifkan key.

Entitlement Management

Kelola entitlement License Key itu sendiri: batas aktivasi, masa berlaku license, dan pesan aktivasi.

Create Entitlement

Buat entitlement License Key.

Update Entitlement

Perbarui konfigurasi entitlement.

List Grants

Tampilkan key yang diterbitkan untuk entitlement.

Revoke Grant

Cabut key customer secara manual.

Webhook

Pengiriman dan pencabutan license key mengirimkan empat entitlement_grant.* webhook events. Untuk grant license key, payload menyertakan objek license_key dengan key, status, masa kedaluwarsa, aktivasi yang digunakan, dan batas aktivasi. Event lama license_key.created tetap berjalan ketika record license key dibuat. Lihat License Key webhook payload page.

Untuk integrasi baru, tangani event entitlement grant, bukan license_key.created. Key yang dipenuhi secara otomatis tiba sebagai entitlement_grant.created dengan status: "Delivered", dan tidak ada event entitlement_grant.delivered terpisah setelahnya. Key yang dipenuhi secara manual memicu entitlement_grant.delivered saat Anda memasoknya. Event yang sama mencakup setiap entitlement pada produk, bukan hanya license key.

License Key Lama

Produk yang dibuat dengan flag license_key_enabled lama telah dimigrasikan secara otomatis ke entitlement License Key. Migrasi ini transparan: key customer yang ada tetap berfungsi, endpoint public /licenses/activate, /licenses/validate, dan /licenses/deactivate tetap berfungsi, dan endpoint API /license_keys/* membaca serta menulis key store yang sama.Bagian dashboard Sales → License Keys yang berdiri sendiri tetap tersedia sebagai daftar datar setiap key yang diterbitkan, untuk audit dan pencarian. Untuk mengubah batas aktivasi, masa berlaku license, atau pesan aktivasi, edit entitlement License Key yang telah dimigrasikan di bawah Entitlements.

Praktik Terbaik

Pilih batas aktivasi yang jelas: pilih default seperti 1 untuk aplikasi satu pengguna atau 3–5 untuk lisensi tim, lalu dokumentasikan untuk customer Anda.
Tulis pesan aktivasi yang tepat: customer menyalinnya dari email license key, jadi path dan command yang akurat dapat mencegah tiket dukungan.
Validasi key terhadap API: untuk produk yang terhubung ke network, panggil /licenses/validate alih-alih mengandalkan aktivasi yang di-cache secara lokal.
Gunakan webhook untuk pencabutan: tangani entitlement_grant.revoked untuk menonaktifkan fitur dalam aplikasi ketika customer membatalkan atau menerima refund.
Uji subscription dan pembelian one-time: perilaku license key berbeda di antara keduanya; misalnya, key subscription tidak kedaluwarsa, jadi uji keduanya sebelum go live.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Apa Itu License Key?

Create a License Key Entitlement

Attach to Products

How Keys Are Issued

Perilaku Quantity

Fulfillment Mode

Manual Fulfillment

Kapan Menggunakannya

Mengaktifkan Manual Fulfillment

Menemukan Grant yang Menunggu Fulfillment

Mengirimkan Key

Aktivasi, Validasi, Deaktivasi

Mengaktifkan License

Memvalidasi License

Menonaktifkan Activation Instance

Mengelola Key

Mengimpor License Key yang Ada melalui API

Perbedaan Key Berdasarkan Sumber

License Key dalam Return URL

Manajemen API

Activate License

Deactivate License

Validate License

Create License Key

List License Keys

Get License Key

Update License Key

Create Entitlement

Update Entitlement

List Grants

Revoke Grant

Webhook

License Key Lama

Praktik Terbaik

​Apa Itu License Key?

​Create a License Key Entitlement

​Attach to Products

​How Keys Are Issued

​Perilaku Quantity

​Fulfillment Mode

​Manual Fulfillment

​Kapan Menggunakannya

​Mengaktifkan Manual Fulfillment

​Menemukan Grant yang Menunggu Fulfillment

​Mengirimkan Key

​Aktivasi, Validasi, Deaktivasi

​Mengaktifkan License

​Memvalidasi License

​Menonaktifkan Activation Instance

​Mengelola Key

​Mengimpor License Key yang Ada melalui API

​Perbedaan Key Berdasarkan Sumber

​License Key dalam Return URL

​Manajemen API

Activate License

Deactivate License

Validate License

Create License Key

List License Keys

Get License Key

Update License Key

Create Entitlement

Update Entitlement

List Grants

Revoke Grant

​Webhook

​License Key Lama

​Praktik Terbaik

Apa Itu License Key?

Create a License Key Entitlement

Attach to Products

How Keys Are Issued

Perilaku Quantity

Fulfillment Mode

Manual Fulfillment

Kapan Menggunakannya

Mengaktifkan Manual Fulfillment

Menemukan Grant yang Menunggu Fulfillment

Mengirimkan Key

Aktivasi, Validasi, Deaktivasi

Mengaktifkan License

Memvalidasi License

Menonaktifkan Activation Instance

Mengelola Key

Mengimpor License Key yang Ada melalui API

Perbedaan Key Berdasarkan Sumber

License Key dalam Return URL

Manajemen API

Webhook

License Key Lama

Praktik Terbaik