功能标志权限

Feature flag entitlement 将 Dodo Payments 转变为具备计费感知能力的 feature flag 存储。将类似 advanced_reports 的 flag 关联到产品后，每位付费客户都会获得一项 grant，您的应用可以通过 API 检查该 grant，或使用 webhooks 保持同步。无需外部平台、OAuth 步骤或交付步骤：grant 本身就是 capability。

交付内容

没有任何内容会离开 Dodo Payments。Grant 就是交付内容：

购买后，Dodo Payments 会直接在 Delivered 中创建 grant。它不会进入 Pending，无需客户执行任何操作，也没有可能失败的交付步骤。
Grant 携带一个类型化的 feature payload：{ "feature_type": "boolean", "feature_id": "advanced_reports" }。您的应用读取 feature_id，以决定要解锁哪些功能。
取消、退款或手动撤销会将 grant 移至 Revoked，并且该 flag 会从客户已交付的 grants 中消失。

常见用途包括基于计划的功能控制（Pro 解锁分析）、附加能力（“API 访问” 升级）和作为一次性购买出售的早期访问计划。

feature_id 是您选择的标识符，在不同 entitlements 之间不具有唯一性。例如，月度和年度 Pro 计划都可以授予 advanced_reports，因此两个 entitlements 可以授予相同的 feature_id。

创建 Feature Flag

Open Entitlements

在 Dodo Payments dashboard 中，前往 Entitlements，点击 + 开始创建新的 entitlement，然后选择 Feature Flags。

Name the Flag

输入用于 dashboard 和报告的 Display Name，并填写 Description，以便团队了解该 flag 控制的内容。Feature ID 是应用检查的标识符。Dashboard 会根据显示名称自动填充该字段（例如，“API access” 会变成 api_access），您也可以对其进行编辑。该字段不能包含空格。

新功能标志表单，具有显示名称、功能ID、描述和元数据键-值条目 — Creating a feature flag. The Feature ID is what your application checks; Meta Data attaches limits alongside the flag.

Add Metadata (Optional)

开启 Meta Data 以附加键值配置，例如限制、层级名称或配额，您的应用会随 flag 一起接收这些配置。每组键值对点击一次 Add Entry。请参阅使用 metadata 附加限制。

Confirm

点击确认。标志会出现在您的权限列表中，准备附加到产品上。

权限控制面板显示高级报告功能标志及其授权活动面板 — The created feature flag. The right pane tracks every customer grant issued from it.

关联到产品

打开一个产品或创建新产品，然后找到 Entitlements 卡片。点击 + 以关联现有 entitlements，选择您的 feature flag，然后点击 Done。

权限附加面板，选择了高级报告功能标志 — Attaching the feature flag to a product. One product can deliver multiple entitlements.

附加的标志显示在产品表单上，结账预览在包含下列出。

产品表单，权限卡中附有高级报告功能标志 — The product now includes the feature flag. Every successful purchase or active subscription grants it.

必需配置

字段	必需	描述
`feature_id`	是	应用检查的标识符，例如 `advanced_reports`。在不同 entitlements 之间不具有唯一性。
`feature_type`	是	所授予 capability 的类型。`boolean` 是唯一支持的值。

通过 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 附加限制

布尔型 flag 可以回答“该客户是否拥有此功能？”。Metadata 可以回答“该功能具有什么配置？”。Entitlement metadata 接受 string、integer、number 和 boolean 值。每个 grant 在创建时都会获取 entitlement metadata 的冻结快照。快照使 metadata 可安全地用于计划限制：

之后编辑 entitlement 的 metadata 只会影响未来创建的 grants。客户仍保留其购买时对应的限制。
每个 grant 都会在其 metadata 字段中返回该快照，因此一次 API 调用即可同时获取 flag 及其配置。

例如，带有 { "tier": "pro", "monthly_report_limit": 100 } 的 advanced_reports flag 可以让您的应用解锁 dashboard，并且执行 100 份报告的配额限制，而无需进行第二次查询。如果之后将限制提高到 250，现有客户仍保持 100 的限制，直到他们获得新的 grant，例如更改计划之后。

使用 metadata 存储限制和配置，仅使用 feature_id 表示身份。将限制编码到 ID 中（advanced_reports_100）会导致每次限制变更都必须创建新的 flag，并破坏应用中的检查逻辑。

检查客户的功能

要构建客户拥有的功能集合，请列出其已交付的 feature flag grants。该 endpoint 会返回所有 entitlements 中每个 grant 对应的一行数据，您可以按 integration_type 和 status 进行筛选。这些示例使用通过 API 创建中的 client。

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

feature payload 仅会在 feature_flag grants 上填充。对于其他所有 integration type，该字段均为 null。完整的响应结构请参阅 List Customer Grants API reference。

每次请求都调用 API 会增加关键路径的延迟。为每个客户的 feature set 设置较短的 TTL（几分钟，而不是几小时），并在 grant 状态发生变化时，通过 webhook handler 使缓存失效。二者结合可以保持检查速度，并让撤销在下一次请求时生效。

生命周期

Feature flag grants 遵循标准的 grant lifecycle，但有一项简化：不存在交付步骤，因此 grants 永远不会停留在 Pending，也不会移动到 Failed。

触发条件	效果
一次性付款成功 / 订阅变为 active	创建 grant，并设置 `status: Delivered` 和 `delivered_at`。
订阅进入 hold、暂停、取消或过期	使用相应的 `revocation_reason` 撤销 grant。
一次性付款退款	使用 `revocation_reason: refund` 撤销 grant。
订阅恢复（例如 dunning 成功）或取消暂停	将已撤销的 grant 恢复到 `Delivered`，使用相同的 grant `id`，并清除撤销字段。
手动 API revoke	使用 `revocation_reason: manual` 撤销 grant。续订时不会自动恢复。

Grants 对每个 entitlement 和客户都是幂等的。当客户拥有某个 flag 的未撤销 grant 时，重复购买和续订不会创建重复项。

Webhooks

要将 flag 镜像到您自己的数据库中，而不是通过轮询获取，请订阅 entitlement_grant.* events：

entitlement_grant.created 到达时已经处于 Delivered，并携带 feature payload。启用该功能。
entitlement_grant.delivered 会在之前撤销的 grant 恢复时触发。再次启用该功能。
entitlement_grant.revoked 表示访问权限已被撤回。禁用该功能，并检查 revocation_reason 以选择要向客户展示的消息。

此 Express handler 使用 SDK 验证 webhook 签名，然后存储 flag 状态：

TypeScript

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

Feature flags 永远不会触发 entitlement_grant.failed，因为交付完全在 Dodo Payments 内部完成。

示例：Pro 计划解锁高级报告

创建 flag。 使用 metadata { "tier": "pro", "monthly_report_limit": 100 } 设置 feature_id: advanced_reports。
关联 flag 到您的 Pro Plan 订阅产品。
客户订阅。 Dodo Payments 创建一个 Delivered grant，并触发 entitlement_grant.created。您的 webhook handler 为该客户启用 advanced_reports，并将限制设为 100。
您的应用控制功能访问。 Dashboard 加载时，检查缓存的 feature set（或调用 listEntitlementGrants），仅当存在 advanced_reports 时才渲染报告标签页。
客户取消订阅。 Dodo Payments 撤销 grant 并触发 entitlement_grant.revoked，您的 handler 会禁用该功能。如果订阅之后通过 dunning 恢复，entitlement_grant.delivered 会恢复该功能，无需更改代码。

最佳实践

在 snake_case 中使用稳定的 feature ID。 应用代码会检查这些字符串，因此重命名其中任何一个都会同时对两端造成 breaking change。
每项 capability 使用一个 flag。 与其使用单个 pro_bundle，不如将 advanced_reports 和 api_access 作为两个 entitlements，这样撤销和计划组合会更清晰。
通过 webhooks 驱动状态，并使用 API 验证。 Webhooks 可以使您的数据库保持最新。List endpoint 是 reconciliation jobs 和 cache misses 的事实来源。
将 Revoked 视为立即生效。 撤销的 flag 表示客户不再为该功能付费。应在下一次请求时进行控制，而不是等到下一次会话。
将限制放入 metadata，而不是代码中。 更改配额时只需编辑 entitlement。新客户会获得新值，现有 grants 则保留其购买时的快照。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

交付内容

创建 Feature Flag

关联到产品

必需配置

通过 API 创建

使用 Metadata 附加限制

检查客户的功能

生命周期

Webhooks

示例：Pro 计划解锁高级报告

最佳实践

​交付内容

​创建 Feature Flag

​关联到产品

​必需配置

​通过 API 创建

​使用 Metadata 附加限制

​检查客户的功能

​生命周期

​Webhooks

​示例：Pro 计划解锁高级报告

​最佳实践

交付内容

创建 Feature Flag

关联到产品

必需配置

通过 API 创建

使用 Metadata 附加限制

检查客户的功能

生命周期

Webhooks

示例：Pro 计划解锁高级报告

最佳实践