跳转到主要内容
授权将成功付款或活跃订阅转换为实际访问：客户收件箱中的许可证密钥、应用检查的功能标志、Discord 角色、GitHub 仓库、Notion 模板、Framer 混音链接、Telegram 聊天邀请或可下载文件包。随着支付生命周期的变化，Dodo Payments 自动发布、跟踪和撤销该访问权限。
Entitlements 导览板，左侧列出entitlements，右侧列出授予活动

​
什么是Entitlements?

Entitlement 是您向客户提供的产品的可重用定义：Pro许可证密钥、“Patrons”Discord角色、私人GitHub存储库的访问权限、可下载的电子书包。您可以将entitlement 附加到产品中，然后Dodo Payments 将处理其余工作。 当客户购买产品时，Dodo Payments 会创建一个 grant，即该entitlement的单个客户发行。Grants会经过一小组状态：在交付进行中时的pending，客户获得访问权限后的delivered，如果交付无法完成的failed，以及访问被撤回时的revoked。
Entitlements 控制交付（客户是否有访问权限？）。Credits 控制消耗（他们可以使用多少？）。两者都可以附加到相同的产品中。查看 Credit-Based Billing 以了解credits。

​
可用集成

Dodo Payments 通过专用集成交付每个entitlement。选择与您销售的产品匹配的集成。

License Keys

生成具有激活限制和到期时间的唯一许可证密钥。最佳用于软件、插件和CLI。

Digital Files

通过预签名的下载URL和可选说明交付可下载文件（电子书、模板、媒体）。

Feature Flags

在您的应用中通过购买来限制功能。即时交付，通过 API 检查，取消时撤销。

Discord

当客户购买时，在您的 Discord 服务器中为其授予角色。取消时自动撤销。

GitHub

在您选择的权限级别上将客户添加为私人仓库的协作者。

Telegram

购买后将客户添加到私人 Telegram 聊天或频道中。

Framer

为付费客户解锁 Framer 模板混音链接。

Notion

将 Notion 模板复制到客户的工作区中。

​
授权工作原理

授权由您已接收为 webhooks 的同一支付和订阅事件驱动。您无需自己调用授权 API 进行购买。Dodo Payments 根据基础支付生命周期自动创建和撤销授权。

​
授权生命周期

1

Created

当付款完成或订阅激活时，会创建授权。许可证密钥和功能标志直接跳转到 delivered。其他集成在 pending 开始。基于 OAuth 的集成（Discord、GitHub、Notion）包括一个客户必须访问以完成同意的 oauth_url。平台直接集成（Telegram、Framer、Digital Files）仅在交付准备期间短暂停留在 pending，然后过渡到 delivered。
2

Delivered

一旦交付完成（生成许可证密钥、分配角色、授予仓库访问权限、解析文件链接、完成 OAuth），授权将移动到 delivered，并设置 delivered_at。
3

Failed

如果集成调用返回不可重试错误（撤销的 OAuth 令牌、拒绝权限、文件不再存在），授权将移动到 failed。error_code 和 error_message 字段捕获原因。
4

Revoked

当访问被撤回（订阅取消、发出退款或商家发起的撤销）时，授权将移动到 revoked。revocation_reason 字段记录触发器。

​
不同事件的授权行为

Event行为
payment.succeeded（一次性付款）每个附加的授权发放一个授权。
payment.succeeded（与订阅相关的付款）无操作。授权由下面的订阅事件驱动。
subscription.active对于尚未收到授权的任何附加授权发放授权。重新授予任何先前为相同订阅撤销的授权。
subscription.renewed无操作。现有授权在续订期间持续存在。
subscription.on_hold撤销所有已交付和待处理的授权。revocation_reason: subscription_on_hold。
subscription.cancelled撤销所有。revocation_reason: subscription_cancelled。
subscription.expired撤销所有。revocation_reason: subscription_expired。
subscription.plan_changed撤销所有现有授权，然后为新计划的授权发放。revocation_reason: plan_changed。
refund.succeeded（一次性付款）撤销该付款的授权。revocation_reason: refund。
Manual API revoke使用 revocation_reason: manual 撤销。手动撤销不会在订阅续订时自动重新授予。
License key disabled对于许可证密钥授权，禁用基础密钥会以 revocation_reason: license_key_disabled 撤销授权。如果密钥重新启用，授权会自动重新激活。
Platform drift detected如果集成的平台端不同步（手动删除 Discord 角色、GitHub 应用失去仓库访问权限或协调时检测到缺失目标），授权会以 revocation_reason: platform_external 撤销。在订阅续订时不会自动重新授予，直到解决基础平台问题。
由订阅驱动的授权对于 (entitlement, customer, subscription) 是幂等的；续订和重新激活不会创建重复的授权。一次性授权对于 (entitlement, customer, payment) 是幂等的。

​
创建您的第一个授权

1

Open Entitlements

在您的 Dodo Payments 仪表板中进入 Entitlements 并单击 + 创建新授权。
2

Pick an integration

选择集成类型：许可证密钥、数字文件、功能标志、Discord、GitHub、Telegram、Framer 或 Notion。对于平台集成，如果尚未连接，请先连接您的账户。
3

Configure delivery

填写特定于集成的字段。例如，GitHub 需要仓库和权限级别；Discord 需要服务器和可选角色；许可证密钥需要激活限制和到期时间。
具有集成选择器和配置字段的新授权表单
4

Save

保存授权。您现在可以将其附加到任何产品上。

​
将授权附加到产品

打开产品，展开 高级设置 → 授权和积分，选择购买产品时应交付的授权。单个产品可以一次交付多个授权。例如，一个专业计划可以包括许可证密钥、GitHub 访问权限和 Discord 角色。
显示每个可用授权的复选框的产品授权选择面板

​
客户体验

​
邮件和客户门户

客户收到购买后包含许可证密钥、下载链接、OAuth 邀请链接或平台邀请的交付邮件，这取决于产品上的授权。相同的详细信息可在他们的 客户门户 中的订单历史记录中无限期地使用。

​
基于 OAuth 的交付

Discord、GitHub 和 Notion 订阅者访问需要客户授权 Dodo Payments 授予他们访问权限。这些授权在客户使用其电子邮件或客户门户中的链接完成 OAuth 流程之前，处于 pending 状态。一旦他们授权，授权将移动到 delivered，并立即提供平台访问。

​
撤销

撤销的授权在平台级别被移除：Discord 角色被移除，GitHub 协作者被移除，许可证密钥被禁用。客户可以在客户门户中看到反映的变化。
对于数字文件，撤销会删除对预签名 URL 的访问，但不会使客户已下载的副本失效。请相应规划内容限制。

​
管理授权

从仪表板打开任何授权以查看其授权。授权详细信息面板显示总授权数、状态过滤器、客户信息、交付日期和撤销操作。 您也可以以编程方式管理授权： 
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});

// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
  status: 'Delivered',
});

// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
  id: 'ent_abc123',
});

client.entitlements.grants.list(
    "ent_abc123",
    status="Delivered",
)

client.entitlements.grants.revoke(
    "grant_xyz789",
    id="ent_abc123",
)

grants, _ := client.Entitlements.Grants.List(
  ctx, "ent_abc123",
  dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)

_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")

​
API 管理

Create Entitlement

创建任意集成类型的新授权。

List Entitlements

通过集成类型进行过滤列出授权。

Get Entitlement

检索授权及其解析的配置。

Update Entitlement

更新名称、描述或集成配置。

Delete Entitlement

软删除授权；现有授权不受影响。

Upload File

上传文件到数字文件授权（最多 500 MiB）。

List Grants

列出授权的所有授权，带有状态和客户过滤器。

Revoke Grant

手动撤销单个授权。

​
Webhooks

Dodo Payments 为授权生命周期触发四个 webhook 事件。订阅这些事件以保持您的应用程序与每个客户的访问权限同步。
Event触发时
entitlement_grant.created创建新授权时。许可证密钥授权到达 delivered；其他每个集成到达 pending，并在平台调用成功后（或基于 OAuth 的集成中，在客户授权后）过渡到 delivered。
entitlement_grant.delivered授权过渡到已交付状态。客户现在拥有访问权限。
entitlement_grant.failed授权无法交付。检查 error_code 和 error_message。
entitlement_grant.revoked访问已被撤回。检查 revocation_reason。

Entitlement Grant Webhook Payloads

查看完整的负载架构、示例事件和 revocation_reason 参考。

​
最佳实践

  • 每个交付渠道使用一个授权。 不要在具有不同角色意图的产品之间共享单个 Discord 授权；为每个角色创建一个，以便于撤销。
  • 首先在测试模式中测试。 创建授权，将其附加到测试产品，进行结账，并观察授权通过 pending → delivered 的过渡。确认取消测试订阅是否撤销授权。
  • 监听 entitlement_grant.delivered，而不是 payment.succeeded。 付款可以在履行完成之前成功（尤其对于 OAuth 流程）。等待交付事件再解锁您自己系统中的依赖功能。
  • 将 entitlement_grant.failed 视为可操作的。 失败的授权意味着客户支付了但未获得访问权限。将这些情况呈现给您的支持团队或触发重新授权。
  • 将 revocation_reason 映射到您的保留流程。 subscription_on_hold 撤销是可恢复的（客户可能会更新他们的卡）。 manual 撤销是有意的。在客户通信中区别对待。
最后修改于 2026年7月9日