> ## 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.
# Pengenalan
> Secara otomatis mengirimkan kunci lisensi, file yang dapat diunduh, dan akses ke platform seperti Discord, GitHub, Telegram, Framer, dan Notion saat pelanggan membayar.
Entitlements mengubah pembayaran yang berhasil atau langganan aktif menjadi akses nyata: kunci lisensi di kotak masuk pelanggan Anda, peran Discord, repositori GitHub, template Notion, tautan remix Framer, undangan obrolan Telegram, atau bundel file yang dapat diunduh. Dodo Payments menerbitkan, melacak, dan mencabut akses tersebut secara otomatis seiring perubahan siklus pembayaran.
## Apa itu Entitlements?
**Entitlement** adalah definisi yang dapat digunakan kembali dari sesuatu yang Anda berikan kepada pelanggan: kunci lisensi Pro, peran Discord "Patrons", akses ke repositori GitHub pribadi Anda, bundel e-book yang dapat diunduh. Anda melampirkan entitlements ke produk, dan Dodo Payments menangani sisanya.
Ketika seorang pelanggan membeli produk, Dodo Payments membuat **grant**, penerbitan entitlement untuk satu pelanggan. Grant bergerak melalui beberapa status: `pending` saat pengiriman sedang berlangsung, `delivered` setelah pelanggan memiliki akses, `failed` jika pengiriman tidak dapat diselesaikan, dan `revoked` ketika akses dicabut.
Entitlements mengatur **fulfillment** (apakah pelanggan memiliki akses?). Kredit mengatur **consumption** (seberapa banyak yang dapat mereka gunakan?). Keduanya dapat dilampirkan ke produk yang sama. Lihat [Credit-Based Billing](/features/credit-based-billing) untuk kredit.
## Integrasi yang Tersedia
Dodo Payments mengirimkan setiap entitlement melalui integrasi khusus. Pilih integrasi yang sesuai dengan apa yang Anda jual.
Hasilkan kunci lisensi unik dengan batas aktivasi dan kedaluwarsa. Terbaik untuk perangkat lunak, plugin, dan CLI.
Kirimkan file yang dapat diunduh (e-book, template, media) dengan URL unduhan yang telah ditandatangani dan instruksi opsional.
Beri pelanggan peran di server Discord Anda saat mereka membeli. Cabut otomatis saat pembatalan.
Tambahkan pelanggan sebagai kolaborator ke repositori pribadi pada tingkat izin yang Anda pilih.
Tambahkan pelanggan ke obrolan atau saluran Telegram pribadi setelah pembelian.
Buka tautan remix template Framer untuk pelanggan yang membayar.
Salin template Notion ke ruang kerja pelanggan saat pembelian.
***
## Bagaimana Grant Bekerja
Grant digerakkan oleh acara pembayaran dan langganan yang sama yang sudah Anda terima sebagai webhook. Anda tidak perlu memanggil grant API sendiri untuk pembelian. Dodo Payments membuat dan mencabut grant secara otomatis berdasarkan siklus pembayaran yang mendasarinya.
### Siklus Hidup Grant
A grant dibuat ketika pembayaran selesai atau langganan menjadi aktif. Kunci lisensi langsung beralih ke `delivered`. Setiap integrasi lainnya dimulai di `pending`. Integrasi berbasis OAuth (Discord, GitHub, Notion) menyertakan `oauth_url` yang harus dikunjungi pelanggan untuk menyelesaikan persetujuan. Integrasi langsung dari platform (Telegram, Framer, File Digital) hanya sebentar berada di `pending` sambil menunggu pengiriman, kemudian beralih ke `delivered`.
Setelah pengiriman selesai (kunci lisensi dihasilkan, peran diberikan, akses repositori diberikan, tautan file diselesaikan, OAuth selesai), grant bergerak ke `delivered` dan `delivered_at` ditetapkan.
Jika panggilan integrasi mengembalikan kesalahan yang tidak dapat diulang (token OAuth dicabut, izin ditolak, file tidak lagi ada), grant bergerak ke `failed`. Bidang `error_code` dan `error_message` menangkap alasannya.
Ketika akses dicabut (langganan dibatalkan, pengembalian dana diberikan, atau pencabutan yang dimulai pedagang), grant bergerak ke `revoked`. Bidang `revocation_reason` mencatat pemicunya.
### Perilaku Grant berdasarkan Acara
| Event | Perilaku |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (pembayaran satu kali) | Keluarkan satu grant untuk setiap entitlement yang dilampirkan. |
| `payment.succeeded` (pembayaran yang terhubung langganan) | Tidak ada operasi. Grant digerakkan oleh acara langganan di bawah. |
| `subscription.active` | Keluarkan grant untuk setiap entitlements yang dilampirkan yang belum memiliki satu. Keluarkan kembali setiap grant yang sebelumnya dicabut untuk langganan yang sama. |
| `subscription.renewed` | Tidak ada operasi. Grant yang ada tetap ada saat perpanjangan. |
| `subscription.on_hold` | Cabut semua grant yang dikirimkan dan tertunda. `revocation_reason: subscription_on_hold`. |
| `subscription.cancelled` | Cabut semua. `revocation_reason: subscription_cancelled`. |
| `subscription.expired` | Cabut semua. `revocation_reason: subscription_expired`. |
| `subscription.plan_changed` | Cabut semua grant saat ini, kemudian keluarkan grant untuk entitlements rencana baru. `revocation_reason: plan_changed`. |
| `refund.succeeded` (pembayaran satu kali) | Cabut grant untuk pembayaran tersebut. `revocation_reason: refund`. |
| Manual API revoke | Cabut dengan `revocation_reason: manual`. Pencabutan manual tidak secara otomatis dikeluarkan ulang saat perpanjangan langganan. |
| License key disabled | Untuk grant dengan kunci lisensi, menonaktifkan kunci yang mendasari mencabut grant dengan `revocation_reason: license_key_disabled`. Grant secara otomatis diaktifkan kembali jika kunci diaktifkan ulang. |
| Platform drift detected | Jika sisi platform dari integrasi keluar dari sinkronisasi (peran Discord dihapus secara manual, Aplikasi GitHub kehilangan akses ke repositori, atau proses rekonsiliasi mendeteksi target yang hilang), grant dicabut dengan `revocation_reason: platform_external`. Tidak secara otomatis dikeluarkan ulang saat perpanjangan langganan hingga masalah platform yang mendasari diselesaikan. |
Grant yang digerakkan oleh langganan adalah idempoten per `(entitlement, customer, subscription)`; pembaruan dan reaktivasi tidak membuat grant duplikat. Grant satu kali adalah idempoten per `(entitlement, customer, payment)`.
***
## Buat entitlement pertama Anda
Pergi ke **Entitlements** di dasbor Dodo Payments Anda dan klik **+** untuk membuat entitlement baru.
Pilih jenis integrasi: License Key, Digital Files, Discord, GitHub, Telegram, Framer, atau Notion. Untuk integrasi platform, hubungkan akun Anda terlebih dahulu jika Anda belum melakukannya.
Isi kolom yang spesifik untuk integrasi. Misalnya, GitHub meminta repositori dan tingkat izin; Discord meminta server dan peran opsional; License Key meminta batas aktivasi dan kedaluwarsa.
Simpan entitlement. Sekarang Anda dapat melampirkannya ke produk apa pun.
## Lampirkan Entitlements ke Produk
Buka produk, perluas **Advanced Settings → Entitlements & Credits**, dan pilih entitlements yang harus dikirimkan saat produk dibeli. Satu produk dapat mengirimkan beberapa entitlements sekaligus. Misalnya, rencana Pro dapat mencakup kunci lisensi, akses GitHub, dan peran Discord.
***
## Pengalaman Pelanggan
### Email dan pusat pelanggan
Pelanggan menerima email pengiriman setelah pembelian yang berisi kunci lisensi, tautan unduhan, tautan undangan OAuth, atau undangan platform, mana yang berlaku untuk entitlements pada produk. Rincian yang sama tetap tersedia tanpa batas dari [Customer Portal](/features/customer-portal) di bawah riwayat pesanan mereka.
### Pengiriman berbasis OAuth
Akses pelanggan Discord, GitHub, dan Notion memerlukan pelanggan untuk mengotorisasi Dodo Payments untuk memberikan akses kepada mereka. Grant ini tetap dalam status `pending` sampai pelanggan menyelesaikan alur OAuth menggunakan tautan dari email mereka atau portal pelanggan. Setelah mereka mengotorisasi, grant bergerak ke `delivered` dan akses platform segera disediakan.
### Pencabutan
Grant yang dicabut dihapus di tingkat platform: peran Discord dihapus, kolaborator GitHub dihapus, kunci lisensi dinonaktifkan. Pelanggan melihat perubahan ini tercermin di portal pelanggan.
Untuk File Digital, pencabutan menghapus akses ke URL yang telah ditandatangani ke depan tetapi tidak membatalkan salinan yang sudah diunduh pelanggan. Rencanakan konten Anda dengan cara ini.
***
## Kelola Grant
Buka salah satu entitlement dari dasbor untuk melihat grant-nya. Panel detail grant menunjukkan total grant, filter status, informasi pelanggan, tanggal pengiriman, dan tindakan pencabutan.
Anda juga dapat mengelola grant secara programatis:
```typescript TypeScript theme={null} theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});
// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
status: 'delivered',
});
// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
path_id: 'ent_abc123',
});
```
```python Python theme={null} theme={null}
client.entitlements.grants.list(
"ent_abc123",
status="delivered",
)
client.entitlements.grants.revoke(
"grant_xyz789",
path_id="ent_abc123",
)
```
```go Go theme={null} theme={null}
grants, _ := client.Entitlements.Grants.List(
ctx, "ent_abc123",
dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)
_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
```
***
## Manajemen API
Buat entitlement baru dari jenis integrasi apa pun.
Daftar entitlements dengan penyaringan berdasarkan jenis integrasi.
Ambil entitlement dan konfigurasi yang diselesaikan.
Perbarui nama, deskripsi, atau konfigurasi integrasi.
Hapus entitlement secara lembut; grant yang ada tidak terpengaruh.
Unggah file ke entitlement File Digital (hingga 100 MB).
Daftar semua grant untuk sebuah entitlement dengan filter status dan pelanggan.
Cabut satu grant secara manual.
***
## Webhook
Dodo Payments memicu empat acara webhook untuk siklus hidup grant. Berlangganan ke acara-acara ini untuk menjaga aplikasi Anda tetap sinkron dengan apa yang dapat diakses setiap pelanggan.
| Event | Dipicu ketika |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement_grant.created` | Grant baru dibuat. Grant kunci lisensi tiba di `delivered`; setiap integrasi lainnya tiba di `pending` dan beralih ke `delivered` setelah panggilan platform berhasil (atau, untuk integrasi berbasis OAuth, setelah pelanggan mengotorisasi). |
| `entitlement_grant.delivered` | Grant beralih ke dikirim. Pelanggan sekarang memiliki akses. |
| `entitlement_grant.failed` | Grant tidak dapat dikirimkan. Periksa `error_code` dan `error_message`. |
| `entitlement_grant.revoked` | Akses telah dicabut. Periksa `revocation_reason`. |
Lihat skema payload lengkap, contoh acara, dan referensi `revocation_reason`.
***
## Praktik Terbaik
* **Gunakan satu entitlement per saluran pengiriman.** Jangan bagikan satu entitlements Discord di seluruh produk dengan maksud peran yang berbeda; buat satu per peran untuk pencabutan yang bersih.
* **Uji terlebih dahulu dalam mode uji.** Buat entitlement, lampirkan ke produk uji, jalankan checkout, dan pantau transisi grant melalui `pending → delivered`. Konfirmasi bahwa pembatalan langganan uji mencabut grant.
* **Dengarkan `entitlement_grant.delivered`, bukan `payment.succeeded`.** Pembayaran bisa berhasil sebelum penyelesaian selesai (terutama untuk alur OAuth). Tunggu acara dikirim sebelum membuka fitur yang bergantung pada sistem Anda sendiri.
* **Anggap `entitlement_grant.failed` sebagai tindakan yang bisa dilakukan.** Grant yang gagal berarti pelanggan membayar tetapi tidak mendapatkan akses. Tampilkan ini ke tim dukungan Anda atau aktifkan regrant.
* **Petakan `revocation_reason` ke alur retensi Anda.** Pencabutan `subscription_on_hold` dapat dipulihkan (pelanggan mungkin memperbarui kartu mereka). Pencabutan `manual` bersifat disengaja. Perlakukan mereka berbeda dalam komunikasi pelanggan.