Feature Flag Entitlement - Dodo Payments Documentation

機能フラグの認可により、Dodo Paymentsを請求対応の機能フラグストアに変えることができます。advanced_reportsのようなフラグを製品に付けると、支払済みの顧客全員に付与が行われ、APIを通じてチェックしたり、Webhookで同期を維持したりできます。外部プラットフォームやOAuth、配信ステップは不要で、付与そのものが機能です。

What gets delivered

Dodo Paymentsからは何も離れません。付与が成果物です：

購入時に付与が作成され、即座にdeliveredに移行します。pendingフェーズはなく、顧客の行動も不要で、配信が失敗することはありません。
付与には型指定されたfeatureペイロードが含まれます：{ "feature_type": "boolean", "feature_id": "advanced_reports" }。アプリケーションはfeature_idを読み込んでどの機能を解除するかを判断します。
キャンセル、払い戻し、または手動による取り消しは、付与をrevokedに移動させ、アプリケーションからフラグが消えることがわかります。

よくある使用例として、プランに基づく機能制御（プロが分析を解除）、アドオン機能（“APIアクセス”のアップグレード）、一度限りの購入として販売されるアーリーアクセスプログラムがあります。

feature_idは商人が選択した識別子で、認可全体にわたって一意ではありません。2つの認可が同じfeature_idを付与することがあります。たとえば、月次および年次のプロプランの両方がadvanced_reportsを付与する場合があります。

Create a feature flag

Open Entitlements

Dodo PaymentsダッシュボードでEntitlementsに移動し、**+**をクリックして新しい認可を開始し、Feature Flagsを選択します。

Name the flag

フラグにダッシュボード用の表示名、アプリケーションが確認する機能ID（ダッシュボードが名前から提案するもの）およびそれが制御する内容をチームに知らせる説明を設定します。

表示名、機能ID、説明、メタデータのキー-バリューエントリを備えた新しい機能フラグフォーム

Optionally add metadata

メタデータを切り替えて、フラグとともにアプリケーションに配信されるキー-バリュー設定（制限、ティエ名、クオータなど）をアタッチします。詳細はメタデータで制限を付けるを参照してください。

Confirm

確認をクリックします。フラグが認可リストに表示され、製品に付属する準備が整います。

付与活動パネルを備えたAdvanced Reports機能フラグを示す認可ダッシュボード

Attach to a product

製品を開く（または作成する）、Entitlementsカードを見つけて**+**をクリックし、既存の認可をアタッチします。機能フラグを選択し、完了をクリックします。

アタッチされたフラグは製品フォームに表示され、チェックアウトプレビューには含まれているとしてリストされます。

EntitlementsカードにAdvanced Reports機能フラグがアタッチされた製品フォーム

Required configuration

Field	Required	Description
`feature_id`	はい	アプリケーションがチェックする識別子、例：`advanced_reports`。認可全体にわたって一意ではありません。
`feature_type`	はい	付与される機能の種類。今日サポートされているのは、`boolean`のみです。

Create via 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"),
    },
  ),
})

Attach limits with metadata

ブールフラグは「この顧客がこの機能を持っていますか？」に答えます。メタデータは「どのような設定で？」に答えます。認可メタデータは文字列、整数、数値、ブール値を受け入れることができ、各認可は作成時に認可のメタデータの固定スナップショットを取得します。このスナップショット動作がメタデータをプランの制限に利用する際の安全性を提供します：

後に認可のメタデータを編集しても、将来の付与にのみ影響します。顧客は購入時の制限が維持されます。
スナップショットは各付与にそのmetadataフィールドとして返されるため、1回のAPIコールでフラグとその設定の両方を取得できます。

たとえば、advanced_reportsフラグと{ "tier": "pro", "monthly_report_limit": 100 }を持つ場合、アプリケーションはダッシュボードを解除し、100件のレポートクオータを強制することができます。後で制限を250に引き上げても、既存の顧客は100のままで、プランが変更されたときに新しい付与を受け取るまで変更されません。

制限や設定にメタデータを使用してください。feature_idはアイデンティティのみに使用します。識別子に制限をエンコードする（advanced_reports_100）は、制限変更のたびに新しいフラグを強制し、アプリケーションのチェックを壊します。

Check a customer’s features

顧客にデリバリーされた機能フラグの付与をリストアップして、利用可能な機能のセットを構築します。このエンドポイントはすべての認可にわたって、付与ごとに1行を返し、integration_typeや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
  }
}

featureペイロードはfeature_flag付与のみに入力されます。他のすべての統合タイプに対してはnullです。完全な応答形状については、List Customer Grants APIリファレンスを参照してください。

毎回のリクエストでAPIをチェックすると、ホットパスに遅延が生じます。顧客ごとの機能セットを短いTTLでキャッシュし（数分、数時間ではない）、付与の状態が変わるとWebhookハンドラからキャッシュを無効化します。この組み合わせで、チェックが速く、取り消しが即座に近くなります。

Lifecycle

機能フラグの付与は、付与のライフサイクルと同じ標準に従いますが、一つ簡素化されています：配信ステップがないため、付与はpendingに置かれることがなく、failedに移動することがありません。

Trigger	Effect
一回払いの成功 / サブスクリプションのアクティブ化	`status: delivered`と`delivered_at`が設定された付与が作成されます。
サブスクリプションの保留、キャンセル、または期限切れ	対応する`revocation_reason`で付与が取り消されます。
一回払いの払い戻し	`revocation_reason: refund`で付与が取り消されます。
サブスクリプションの回復（例えば、督促が成功）	無効になった付与が`delivered`に復元されます。 — 同じ付与`id`で、取り消しフィールドがクリアされます。
手動API取り消し	`revocation_reason: manual`で付与が取り消されます。更新時には自動復元されません。

付与は認可および顧客ごとに冪等性を持ちます：顧客がフラグの未取り消しの付与を持つ間は、リピート購入と更新は重複を作成しません。

Webhooks

entitlement_grant.*イベントを購読して、フラグをポーリングする代わりに自分のデータベースにミラーリングします：

entitlement_grant.created — deliveredとしてすでに到着しており、featureペイロード付きです。機能を有効にします。
entitlement_grant.delivered — 以前に取り消された付与が復元されたときに発火します。機能を再有効化します。
entitlement_grant.revoked — アクセスが取り消されました。機能を無効にし、メッセージングを決定するためにrevocation_reasonを確認します。

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

機能フラグに対してentitlement_grant.failedはありません — 配信は完全にDodo Payments内で行われ、失敗することはありません。

Example: Pro plan unlocks advanced reports

フラグを作成します。 feature_id: advanced_reportsとメタデータ{ "tier": "pro", "monthly_report_limit": 100 }。
それをプロプランのサブスクリプション製品にアタッチします。
顧客がサブスクライブします。 Dodo Paymentsがdeliveredの付与を作成し、entitlement_grant.createdを発火します。Webhookハンドラが顧客のために100の制限でadvanced_reportsを有効にします。
アプリが機能を制御します。 ダッシュボードのロード時にキャッシュされた機能セットを確認（またはlistEntitlementGrantsを呼び出して）、advanced_reportsが存在する場合のみレポートタブを表示します。
顧客がキャンセルします。 Dodo Paymentsが付与を取り消し、entitlement_grant.revokedを発火します。ハンドラが機能を無効にします。顧客が督促を介して後で回復すると、entitlement_grant.deliveredがそれを復元します — コードの変更は不要です。

Best practices

安定したsnake_case機能IDを使用します。 アプリケーションコードはこれらの文字列をチェックします。名前を変更することは、両側での破壊的変更です。
1つの機能につき1つのフラグ。 SINGLE_advanced_reports + api_accessを2つの認可として選択し、単一のpro_bundleとします。取り消しおよびプランの組み合わせがスムーズになります。
状態をwebhooksで駆動し、APIで検証します。 Webhooksはデータベースを最新に保ちます。リストエンドポイントは、調整ジョブとキャッシュミスのための真実の源です。
revokedを即時とみなします。 取り消されたフラグは、顧客がもはやその機能に対して支払っていないことを意味します。次のリクエストで、次のセッションではなく制御します。
メタデータに制限を設定し、コードには設定しません。 クオータを変更する場合、それは認可の編集だけを必要とし、新しい顧客は自動的にそれを取り入れ、既存の付与は購入したスナップショットを維持します。

​What gets delivered

​Create a feature flag

​Attach to a product

​Required configuration

​Create via API

​Attach limits with metadata

​Check a customer’s features

​Lifecycle

​Webhooks

​Example: Pro plan unlocks advanced reports

​Best practices

What gets delivered

Create a feature flag

Attach to a product

Required configuration

Create via API

Attach limits with metadata

Check a customer’s features

Lifecycle

Webhooks

Example: Pro plan unlocks advanced reports

Best practices