Hak Fitur Bendera

Hak fitur bendera mengubah Dodo Payments menjadi penyimpanan fitur-bendera yang sadar-billing. Lampirkan bendera seperti advanced_reports ke produk, dan setiap pelanggan yang membayar mendapatkan hak yang dapat diuji aplikasi Anda melalui API atau disinkronkan dengan webhooks. Tanpa platform eksternal, tanpa OAuth, tanpa langkah pengiriman — hak itu sendiri adalah kemampuan.

Apa yang disampaikan

Tidak ada yang meninggalkan Dodo Payments — hak itu adalah yang disampaikan:

Saat pembelian, grant dibuat dan langsung berpindah ke Delivered. Tidak ada fase Pending, tidak ada tindakan pelanggan, dan tidak ada kemungkinan delivery gagal.
Grant membawa payload feature bertipe: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Aplikasi Anda membaca feature_id untuk menentukan apa yang harus dibuka.
Pembatalan, refund, atau pencabutan manual memindahkan grant ke Revoked, dan aplikasi Anda melihat flag tersebut menghilang.

Penggunaan umum termasuk pembatasan fitur berdasarkan rencana (Pro membuka analitik), kemampuan tambahan (peningkatan “akses API”), dan program akses awal yang dijual sebagai pembelian satu kali.

feature_id adalah pengidentifikasi yang dipilih oleh pedagang, tidak unik di seluruh hak. Dua hak dapat memberikan feature_id yang sama — misalnya, rencana Pro bulanan dan tahunan keduanya memberikan advanced_reports.

Membuat fitur bendera

Open Entitlements

Di dashboard Dodo Payments Anda, masuk ke Entitlements dan klik + untuk memulai hak baru, lalu pilih Feature Flags.

Name the flag

Berikan Display Name untuk dashboard Anda, Feature ID yang akan diperiksa aplikasi Anda (dashboard menyarankan satu dari nama), dan Description agar tim Anda tahu apa yang dikendalikannya.

Form Fitur Bendera Baru dengan nama tampilan, ID fitur, deskripsi, dan entri kunci-nilai metadata — Creating a feature flag. The Feature ID is what your application checks; Meta Data attaches limits alongside the flag.

Optionally add metadata

Toggle Meta Data untuk melampirkan konfigurasi kunci-nilai — batas, nama tier, kuota — yang disampaikan ke aplikasi Anda bersamaan dengan bendera. Lihat Lampirkan batas dengan metadata.

Confirm

Klik Confirm. Bendera muncul di daftar hak Anda, siap dilampirkan ke produk.

Dasbor Entitlements menampilkan bendera fitur Advanced Reports dengan panel aktivitas haknya — The created feature flag. The right pane tracks every customer grant issued from it.

Lampirkan ke produk

Buka produk (atau buat satu), temukan kartu Entitlements, dan klik + untuk melampirkan hak yang ada. Pilih fitur bendera Anda dan klik Selesai.

Panel lampiran Entitlements dengan bendera fitur Advanced Reports dipilih — Attaching the feature flag to a product. One product can deliver multiple entitlements.

Bendera yang dilampirkan ditampilkan pada formulir produk, dan pratinjau checkout mencantumkannya di bawah Includes.

Formulir produk dengan bendera fitur Advanced Reports dilampirkan di kartu Entitlements — The product now includes the feature flag. Every successful purchase or active subscription grants it.

Konfigurasi yang diperlukan

Field	Diperlukan	Deskripsi
`feature_id`	Ya	Pengidentifikasi yang diperiksa aplikasi Anda, mis. `advanced_reports`. Tidak unik di seluruh hak.
`feature_type`	Ya	Jenis kemampuan yang diberikan. Hanya `boolean` yang didukung hari ini.

Buat melalui API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode',
});

const entitlement = await client.entitlements.create({
  name: 'Advanced Reports',
  integration_type: 'feature_flag',
  integration_config: {
    feature_type: 'boolean',
    feature_id: 'advanced_reports',
  },
  metadata: {
    tier: 'pro',
    monthly_report_limit: 100,
  },
});

client.entitlements.create(
    name="Advanced Reports",
    integration_type="feature_flag",
    integration_config={
        "feature_type": "boolean",
        "feature_id": "advanced_reports",
    },
    metadata={
        "tier": "pro",
        "monthly_report_limit": 100,
    },
)

client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
  Name:            dodopayments.F("Advanced Reports"),
  IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeFeatureFlag),
  IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
    dodopayments.IntegrationConfigFeatureFlagConfigParam{
      FeatureType: dodopayments.F(dodopayments.FeatureTypeBoolean),
      FeatureID:   dodopayments.F("advanced_reports"),
    },
  ),
})

Lampirkan batas dengan metadata

Bendera boolean menjawab “apakah pelanggan ini memiliki fitur?”. Metadata menjawab “dengan konfigurasi apa?”. Metadata hak menerima nilai string, integer, angka, dan boolean, dan setiap hak mengambil snapshot beku dari metadata hak pada saat dibuat. Perilaku snapshot adalah yang membuat metadata aman untuk digunakan untuk batas rencana:

Mengedit metadata dari hak nantinya hanya mempengaruhi hak masa depan. Pelanggan menyimpan batas yang mereka beli.
Snapshot dikembalikan pada setiap hak sebagai bidang metadata-nya, jadi satu panggilan API memberi Anda bendera dan konfigurasinya.

Misalnya, bendera advanced_reports dengan { "tier": "pro", "monthly_report_limit": 100 } memungkinkan aplikasi Anda membuka dasbor dan menegakkan kuota 100 laporan tanpa pencarian kedua. Jika Anda kemudian menaikkan batas menjadi 250, pelanggan yang ada tetap pada 100 hingga mereka menerima hak baru (misalnya, setelah perubahan rencana).

Gunakan metadata untuk batas dan konfigurasi; gunakan feature_id hanya untuk identitas. Mengencode batas dalam id (advanced_reports_100) memaksa bendera baru untuk setiap perubahan batas dan merusak pengecekan aplikasi Anda.

Periksa fitur pelanggan

Daftar hak fitur-bendera yang diberikan kepada pelanggan dan buat set fitur yang diaktifkan. Endpoint mengembalikan satu baris per hak di seluruh hak, dapat difilter dengan integration_type dan status.

const features = new Map<string, Record<string, unknown>>();

for await (const grant of client.customers.listEntitlementGrants('cus_abc123', {
  integration_type: 'feature_flag',
  status: 'Delivered',
})) {
  if (grant.feature) {
    features.set(grant.feature.feature_id, grant.metadata ?? {});
  }
}

if (features.has('advanced_reports')) {
  const limit = features.get('advanced_reports')?.monthly_report_limit;
  // unlock the dashboard, enforce the limit
}

page = client.customers.list_entitlement_grants(
    customer_id="cus_abc123",
    integration_type="feature_flag",
    status="Delivered",
)

features = {
    grant.feature.feature_id: grant.metadata
    for grant in page.items
    if grant.feature
}

if "advanced_reports" in features:
    limit = features["advanced_reports"].get("monthly_report_limit")

page, _ := client.Customers.ListEntitlementGrants(
  ctx, "cus_abc123",
  dodopayments.CustomerListEntitlementGrantsParams{
    IntegrationType: dodopayments.F("feature_flag"),
    Status:          dodopayments.F("Delivered"),
  },
)

features := map[string]bool{}
for _, grant := range page.Items {
  if grant.Feature.FeatureID != "" {
    features[grant.Feature.FeatureID] = true
  }
}

Payload feature diisi hanya pada grant feature_flag; ini adalah null untuk setiap jenis integrasi lainnya. Lihat referensi API List Customer Grants untuk bentuk tanggapan lengkapnya.

Memeriksa API pada setiap permintaan menambah latensi pada jalur panas Anda. Cache set fitur per pelanggan dengan waktu hidup yang sebentar (menit, bukan jam), dan batalkan cache dari handler webhook Anda saat hak berubah status — kombinasi itu menjaga pengecekan tetap cepat dan pencabutan hampir seketika.

Siklus hidup

Grant feature flag mengikuti siklus hidup grant standar dengan satu penyederhanaan: tidak ada langkah delivery, sehingga grant tidak pernah berada di Pending dan tidak pernah berpindah ke Failed.

Pemicu	Efek
Pembayaran satu kali berhasil / subscription menjadi aktif	Grant dibuat dengan `status: delivered` dan `delivered_at` yang telah diatur.
Subscription ditangguhkan, dibatalkan, atau kedaluwarsa	Grant dicabut dengan `revocation_reason` yang sesuai.
Refund untuk pembayaran satu kali	Grant dicabut dengan `revocation_reason: refund`.
Subscription pulih (misalnya, dunning berhasil)	Grant yang dicabut dipulihkan ke `Delivered` — `id` grant tetap sama, kolom pencabutan dihapus.
Pencabutan API manual	Grant dicabut dengan `revocation_reason: manual`. Tidak dipulihkan secara otomatis saat perpanjangan.

Hak adalah idempotent per hak dan pelanggan: sementara pelanggan memiliki hak untuk bendera yang tidak dicabut, pembelian ulang dan pembaruan tidak menciptakan duplikat.

Webhooks

Berlangganan ke entitlement_grant.* events untuk menyinkronkan bendera ke dalam database Anda sendiri daripada polling:

entitlement_grant.created — sudah tiba dalam status Delivered dengan payload feature. Aktifkan feature tersebut.
entitlement_grant.delivered — dijalankan saat grant yang sebelumnya dicabut dipulihkan. Aktifkan kembali feature tersebut.
entitlement_grant.revoked — akses dicabut. Nonaktifkan feature tersebut dan periksa revocation_reason untuk menentukan pesan yang akan ditampilkan.

TypeScript

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  if (event.type.startsWith('entitlement_grant.') && event.data.feature) {
    const { customer_id, feature } = event.data;
    const enabled = event.type !== 'entitlement_grant.revoked';

    await db.customerFeatures.upsert({
      customerId: customer_id,
      featureId: feature.feature_id,
      enabled,
      config: event.data.metadata ?? {},
    });
  }

  res.sendStatus(200);
});

Tidak ada entitlement_grant.failed untuk fitur bendera — pengiriman terjadi sepenuhnya di dalam Dodo Payments dan tidak dapat gagal.

Contoh: Rencana Pro membuka laporan lanjutan

Buat flag. feature_id: advanced_reports dengan metadata { "tier": "pro", "monthly_report_limit": 100 }.
Lampirkan flag tersebut ke produk subscription Pro Plan Anda.
Pelanggan berlangganan. Dodo Payments membuat grant Delivered dan menjalankan entitlement_grant.created; webhook handler Anda mengaktifkan advanced_reports untuk pelanggan dengan limit 100.
Aplikasi Anda membatasi akses ke feature. Saat dashboard dimuat, periksa feature set yang di-cache (atau panggil listEntitlementGrants) dan tampilkan tab laporan hanya jika advanced_reports tersedia.
Pelanggan membatalkan subscription. Dodo Payments mencabut grant dan menjalankan entitlement_grant.revoked; handler Anda menonaktifkan feature tersebut. Jika pelanggan kemudian pulih melalui dunning, entitlement_grant.delivered memulihkannya — tidak diperlukan perubahan kode.

Praktik Terbaik

Gunakan feature id snake_case yang stabil. Kode aplikasi Anda memeriksa string ini; mengganti namanya merupakan breaking change di kedua sisi.
Satu flag untuk setiap kapabilitas. Lebih baik gunakan advanced_reports + api_access sebagai dua entitlement daripada satu pro_bundle — pencabutan dan kombinasi plan tetap rapi.
Dorong state dari webhook, verifikasi dengan API. Webhook menjaga database Anda tetap mutakhir; list endpoint adalah sumber kebenaran untuk reconciliation job dan cache miss.
Perlakukan Revoked sebagai tindakan segera. Flag yang dicabut berarti pelanggan tidak lagi membayar feature tersebut. Batasi akses pada request berikutnya, bukan session berikutnya.
Tempatkan limit di metadata, bukan di kode. Dengan begitu, perubahan kuota hanya memerlukan pengeditan entitlement — pelanggan baru akan menggunakannya secara otomatis, sementara grant yang sudah ada tetap mempertahankan snapshot yang dibeli.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Apa yang disampaikan

Membuat fitur bendera

Lampirkan ke produk

Konfigurasi yang diperlukan

Buat melalui API

Lampirkan batas dengan metadata

Periksa fitur pelanggan

Siklus hidup

Webhooks

Contoh: Rencana Pro membuka laporan lanjutan

Praktik Terbaik

​Apa yang disampaikan

​Membuat fitur bendera

​Lampirkan ke produk

​Konfigurasi yang diperlukan

​Buat melalui API

​Lampirkan batas dengan metadata

​Periksa fitur pelanggan

​Siklus hidup

​Webhooks

​Contoh: Rencana Pro membuka laporan lanjutan

​Praktik Terbaik

Apa yang disampaikan

Membuat fitur bendera

Lampirkan ke produk

Konfigurasi yang diperlukan

Buat melalui API

Lampirkan batas dengan metadata

Periksa fitur pelanggan

Siklus hidup

Webhooks

Contoh: Rencana Pro membuka laporan lanjutan

Praktik Terbaik