Feature Flag Entitlement

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

What gets delivered

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

購入時に grant が作成され、すぐに Delivered へ移行します。Pending フェーズはなく、顧客による操作も、delivery が失敗する可能性もありません。
grant には型付きの feature ペイロード（{ "feature_type": "boolean", "feature_id": "advanced_reports" }）が含まれます。アプリケーションは feature_id を読み取り、アンロックする機能を決定します。
キャンセル、refund、または手動 revoke により grant は 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、説明、メタデータのキー-バリューエントリを備えた新しい機能フラグフォーム — Creating a feature flag. The Feature ID is what your application checks; Meta Data attaches limits alongside the flag.

Optionally add metadata

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

Confirm

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

付与活動パネルを備えたAdvanced Reports機能フラグを示す認可ダッシュボード — The created feature flag. The right pane tracks every customer grant issued from it.

Attach to a product

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

Advanced Reports機能フラグが選択された認可アタッチパネル — Attaching the feature flag to a product. One product can deliver multiple entitlements.

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

EntitlementsカードにAdvanced Reports機能フラグがアタッチされた製品フォーム — The product now includes the feature flag. Every successful purchase or active subscription grants it.

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

Feature flag の grant は標準の grant lifecycle に従いますが、delivery step がないという簡略化が加えられています。そのため、grant が Pending に留まることも、Failed へ移行することもありません。

Trigger	Effect
One-time payment succeeds / subscription becomes active	`status: delivered` と `delivered_at` が設定された状態で grant が作成されます。
Subscription put on hold, cancelled, or expired	対応する `revocation_reason` により grant が revoke されます。
Refund on a one-time payment	`revocation_reason: refund` により grant が revoke されます。
Subscription recovers (for example, dunning succeeds)	revoke された grant が `Delivered` に復元されます — 同じ grant の `id` で、revoke フィールドはクリアされます。
Manual API revoke	`revocation_reason: manual` により grant が revoke されます。更新時に自動復元されることはありません。

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

Webhooks

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

entitlement_grant.created — すでに Delivered の状態で、feature ペイロードとともに届きます。機能を有効にします。
entitlement_grant.delivered — 以前 revoke された grant が復元されたときに発生します。機能を再度有効にします。
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 } を設定します。
Pro Plan の subscription product にアタッチします。
顧客がサブスクライブします。 Dodo Payments が Delivered grant を作成して entitlement_grant.created を発生させます。webhook handler は顧客に対して advanced_reports を有効にし、上限を 100 に設定します。
アプリで機能を制御します。 dashboard の読み込み時に、キャッシュされた feature set を確認するか listEntitlementGrants を呼び出し、advanced_reports が存在する場合にのみ reports タブを表示します。
顧客がキャンセルします。 Dodo Payments が grant を revoke して entitlement_grant.revoked を発生させ、handler が機能を無効にします。後で顧客が dunning によって回復した場合は、entitlement_grant.delivered により機能が復元されます — コードの変更は必要ありません。

Best practices

安定した snake_case の feature id を使用します。 アプリケーションコードはこれらの文字列をチェックするため、1 つでも名前を変更すると双方で breaking change になります。
機能ごとに 1 つのフラグを使用します。 1 つの pro_bundle にまとめるよりも、advanced_reports と api_access の 2 つの entitlement を使用する方が、revoke やプランの組み合わせを適切に管理できます。
webhook を使って状態を更新し、API で検証します。 webhook によりデータベースを最新に保ち、list endpoint は reconciliation job とキャッシュミスにおける source of truth になります。
Revoked を即時のものとして扱います。 revoke されたフラグは、顧客がその機能に対して料金を支払っていないことを意味します。次の session ではなく、次の request でアクセスを制御してください。
制限値はコードではなく metadata に設定します。 quota の変更が必要になった場合も entitlement を編集するだけで済みます。新しい顧客には自動的に適用され、既存の grant には購入時のスナップショットが保持されます。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

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

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