功能标志权限

一个功能标志权限将 Dodo Payments 转变为一个与账单相关的功能标志存储。将类似于 advanced_reports 的标志附加到产品上，每个支付客户都能通过 API 检查或使用 webhooks 保持同步来获得授权。无需外部平台，无需 OAuth，无需交付步骤 — 授权本身就是能力。

交付内容

没有任何东西离开 Dodo Payments — 授权就是交付物:

购买后，grant 会被创建，并直接进入 Delivered。不存在 Pending 阶段，不需要客户执行任何操作，交付也不会失败。
grant 携带类型化的 feature payload：{ "feature_type": "boolean", "feature_id": "advanced_reports" }。您的应用读取 feature_id，以决定解锁哪些内容。
取消、退款或手动撤销会将 grant 移至 Revoked，您的应用会看到该标志消失。

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

feature_id 是商家选择的标识符，不在所有权限中唯一。两个权限可以提供相同的 feature_id —— 例如，月度和年度 Pro 计划都授予 advanced_reports。

创建功能标志

Open Entitlements

在您的 Dodo Payments 控制面板中，转到权限并点击 + 开始一个新权限，然后选择 功能标志。

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

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

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

附加到产品

打开一个产品（或创建一个），找到权限卡，然后点击 + 以附加现有权限。选择您的功能标志并点击完成。

权限附加面板，选择了高级报告功能标志 — 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`。未在权限中唯一。
`feature_type`	是	授予的能力类型。当前仅支持 `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,
  },
});

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

用元数据附加限制

一个布尔标志回答“此客户是否拥有该功能？”。元数据回答“使用什么配置？”。权限元数据接受字符串、整数、数字和布尔值，每个授权在创建时会对权限的元数据进行冻结快照。这种快照行为使得元数据在计划限制中使用安全：

稍后编辑权限的元数据仅影响未来的授权。客户保留他们购买时的限制。
每个授权都在其 metadata 字段中返回快照，因此一个 API 调用可以同时提供标志及其配置。

例如，一个具有 { "tier": "pro", "monthly_report_limit": 100 } 的 advanced_reports 标志让您的应用程序解锁仪表板并执行 100 份报告配额，而无需第二次查找。如果您后来将限制提高到 250，现有客户仍为 100，直到他们收到新的授权（例如，计划更改后）。

使用元数据进行限制和配置；仅对身份使用 feature_id。在 id 中编码限制（advanced_reports_100）会在每次限制更改时强制创建新标志，并破坏应用程序的检查。

检查客户的功能

列出客户交付的功能标志授权，并构建已启用功能集。终端返回每个授权跨所有权限的一行，支持按 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。完整响应格式请参见列出客户授权 API 参考。

在每个请求上检查 API 会增加热路径的延迟。使用短 TTL（分钟而非小时）为每个客户缓存功能集，并在授权变更状态时从您的 webhook 处理程序中使缓存无效 —— 这种结合保持检查快速，并使撤销接近于即时。

生命周期

Feature flag grant 遵循标准的 grant lifecycle，但进行了简化：不存在交付步骤，因此 grant 永远不会停留在 Pending，也不会转移到 Failed。

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

授权对于每个权限和客户是幂等的：当客户对一个标志拥有未撤销的授权时，重复购买和续订不会创建重复项。

Webhooks

订阅 entitlement_grant.* 事件以将标志镜像到您自己的数据库而不是轮询：

entitlement_grant.created — 到达时已处于 Delivered，并携带 feature payload。启用该功能。
entitlement_grant.delivered — 之前被撤销的 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 内部进行，不能失败。

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

创建 flag。 使用元数据 { "tier": "pro", "monthly_report_limit": 100 } 执行 feature_id: advanced_reports。
附加该 flag 到您的 Pro Plan subscription product。
客户订阅。 Dodo Payments 创建一个 Delivered grant，并触发 entitlement_grant.created；您的 webhook handler 为该客户启用 advanced_reports，限制为 100。
您的应用控制功能访问。 加载 dashboard 时，检查缓存的 feature set（或调用 listEntitlementGrants），仅当存在 advanced_reports 时才渲染 reports tab。
客户取消订阅。 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 作为两个 entitlement — 这样撤销和 plan 组合能够保持清晰。
由 webhook 驱动状态，并通过 API 验证。 Webhook 会使您的数据库保持最新；list endpoint 是 reconciliation job 和 cache miss 场景的事实来源。
将 Revoked 视为立即生效。 被撤销的 flag 意味着客户不再为该功能付费。应在下一次请求时进行访问控制，而不是等到下一次 session。
将限制放在元数据中，而不是代码中。 这样更改 quota 时只需编辑 entitlement — 新客户会自动获得更新后的限制，而现有 grant 会保留其购买时的快照。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

交付内容

创建功能标志

附加到产品

必需配置

通过 API 创建

用元数据附加限制

检查客户的功能

生命周期

Webhooks

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

最佳实践

​交付内容

​创建功能标志

​附加到产品

​必需配置

​通过 API 创建

​用元数据附加限制

​检查客户的功能

​生命周期

​Webhooks

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

​最佳实践

交付内容

创建功能标志

附加到产品

必需配置

通过 API 创建

用元数据附加限制

检查客户的功能

生命周期

Webhooks

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

最佳实践