Feature Flag Entitlement

​

配信されるもの

• 購入時、Dodo Payments は Delivered に grant を直接作成します。Pending に入ることはなく、customer の操作も不要で、失敗する可能性のある delivery step もありません。
• grant には型付きの feature payload が含まれます: { "feature_type": "boolean", "feature_id": "advanced_reports" }。アプリケーションは feature_id を読み取り、unlock する機能を決定します。
• Cancellation、refund、または手動の revoke により、grant は Revoked に移行し、customer に配信された grant から flag が消えます。

​

Feature Flag の作成

1

Open Entitlements

Dodo Payments dashboard で Entitlements に移動し、+ をクリックして新しい entitlement の作成を開始し、Feature Flags を選択します。

2

Name the Flag

dashboard と reports に表示する Display Name と、flag が制御する内容をチームが把握できるように Description を入力します。Feature ID はアプリケーションが確認する値です。dashboard では display name から自動入力されます（たとえば、“API access” は api_access になります）が、編集もできます。スペースは使用できません。

3

Add Metadata (Optional)

Meta Data をオンにすると、limits、tier names、quotas などの key-value configuration を flag とともにアプリケーションへ渡せます。各ペアについて Add Entry をクリックします。metadata で limits を紐付ける を参照してください。

4

Confirm

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

​

Product への紐付け

​

必須 Configuration

​

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

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

entitlement = 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 is a *dodopayments.Client, for example from
// dodopayments.NewClient(option.WithEnvironmentTestMode()); ctx is a context.Context.
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"),
    },
  ),
})

​

Metadata で Limits を紐付ける

• 後から entitlement の metadata を編集しても影響するのは future の grant のみです。customer は購入時の limits を維持します。
• 各 grant は metadata field に snapshot を返すため、1 回の API call で flag とその configuration の両方を取得できます。

​

Customer の Features を確認する

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",
)

# Iterating the page fetches every page of results.
features = {
    grant.feature.feature_id: grant.metadata
    for grant in page
    if grant.feature
}

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

iter := client.Customers.ListEntitlementGrantsAutoPaging(
  ctx, "cus_abc123",
  dodopayments.CustomerListEntitlementGrantsParams{
    IntegrationType: dodopayments.F(dodopayments.CustomerListEntitlementGrantsParamsIntegrationTypeFeatureFlag),
    Status:          dodopayments.F(dodopayments.CustomerListEntitlementGrantsParamsStatusDelivered),
  },
)

features := map[string]bool{}
for iter.Next() {
  grant := iter.Current()
  if grant.Feature.FeatureID != "" {
    features[grant.Feature.FeatureID] = true
  }
}
if err := iter.Err(); err != nil {
  panic(err.Error())
}

​

Lifecycle

​

Webhooks

• entitlement_grant.created は、Delivered の状態で、feature payload とともに届きます。feature を有効にします。
• entitlement_grant.delivered は、以前に revoked された grant が復元されたときに発生します。feature を再度有効にします。
• entitlement_grant.revoked は access が取り消されたことを示します。feature を無効にし、メッセージを決定するために revocation_reason を確認します。

import express from 'express';
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_WEBHOOK_KEY from the environment.
const client = new DodoPayments({ environment: 'test_mode' });
const app = express();

app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: DodoPayments.UnwrapWebhookEvent;
  try {
    event = client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers as Record<string, string>,
    });
  } catch {
    res.sendStatus(400); // invalid signature
    return;
  }

  const grant = 'feature' in event.data ? event.data : null;

  if (event.type.startsWith('entitlement_grant.') && grant?.feature) {
    const enabled = event.type !== 'entitlement_grant.revoked';

    // db is your application's database client.
    await db.customerFeatures.upsert({
      customerId: grant.customer_id,
      featureId: grant.feature.feature_id,
      enabled,
      config: grant.metadata ?? {},
    });
  }

  res.sendStatus(200);
});

​

Example: Pro Plan で Advanced Reports を Unlock する

1. flag を作成します。 feature_id: advanced_reports を設定し、{ "tier": "pro", "monthly_report_limit": 100 } の metadata を追加します。
2. 紐付けます。 Pro Plan subscription product に紐付けます。
3. customer が subscribe します。 Dodo Payments は Delivered grant を作成し、entitlement_grant.created を発火します。webhook handler は customer に対して advanced_reports を有効にし、limit を 100 に設定します。
4. アプリが feature を gate します。 dashboard の load 時に cached feature set を確認するか listEntitlementGrants を呼び出し、advanced_reports が存在する場合にのみ reports tab を render します。
5. customer がキャンセルします。 Dodo Payments は grant を revoke して entitlement_grant.revoked を発火し、handler は feature を無効にします。subscription が後から dunning によって回復すると、entitlement_grant.delivered が feature を復元します。コード変更は必要ありません。

​

Best Practices

• snake_case では stable な feature IDs を使用します。 アプリケーション code はこれらの strings を確認するため、名前の変更は双方にとって breaking change になります。
• capability ごとに 1 つの flag を使用します。 1 つの pro_bundle よりも、advanced_reports と api_access を 2 つの entitlements として使用することを推奨します。これにより revoke と plan combinations を適切に管理できます。
• webhooks を state の source とし、API で検証します。 Webhooks により database を最新に保てます。list endpoint は reconciliation jobs と cache misses における source of truth です。
• Revoked を immediate として扱います。 revoked flag は、customer がその feature の料金を支払わなくなったことを意味します。次の session ではなく、次の request で gate してください。
• limits は code ではなく metadata に設定します。 quota の変更は entitlement の編集だけで済みます。新しい customer には新しい値が適用され、既存の grants には購入時の snapshot が維持されます。