介绍

当客户付款时，自动交付许可证密钥、可下载文件、功能标志，以及访问Discord、GitHub、Telegram、Framer和Notion等平台的权限。

权限将成功付款或活跃订阅转化为实际访问权限：您的客户邮箱中的许可证密钥、您的应用检测的功能标志、Discord角色、GitHub仓库、Notion模板、Framer混编链接、Telegram聊天邀请或可下载文件包。随着付款生命周期的变化，Dodo Payments会自动发放、跟踪和撤销这些访问权限。

The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.

​

什么是权限？

一个权限是您交付给客户的某种可重复使用的定义：例如Pro许可证密钥、“Patrons”Discord角色、您私人GitHub仓库的访问权限、可下载的电子书包。您可以将权限附加到产品上，Dodo Payments会负责其余的工作。

当客户购买产品时，Dodo Payments会创建一个授予，这是对某个单一客户的该权限的发放。授予通过一小组状态转换：pending 表示交付正在进行中，delivered 表示客户已获得访问权限，failed 表示无法完成交付，revoked 表示访问已被撤回。

权限控制履行（客户是否有访问权限？）。信用控制消费（他们能使用多少？）。两者都可以附加到同一产品上。查看基于信用的计费了解关于信用的信息。

​

可用集成

Dodo Payments通过专门的集成交付每个权限。选择匹配您销售内容的集成。

License Keys

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

Digital Files

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

Feature Flags

在您自己的应用中启用购买功能。即时交付，通过API检测，取消时撤销。

Discord

当客户购买时，为其在你的Discord服务器中分配一个角色。取消时自动撤销。

GitHub

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

Telegram

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

Framer

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

Notion

购买时将Notion模板复制到客户的工作区。

---

​

授予的工作原理

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

​

授予生命周期

1. Created

   在付款完成或订阅激活时创建授予。许可证密钥和功能标志会直接跳到 delivered。所有其他集成从 pending 开始。基于OAuth的集成（Discord、GitHub、Notion）包括客户必须访问的 oauth_url 来完成授权。平台直接集成（Telegram、Framer、数字文件）只是短暂地处于 pending，同时交付被配置，然后过渡到 delivered。

2. Delivered

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

3. Failed

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

4. Revoked

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

​

事件驱动的授予行为

事件	行为
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。
手动API撤销	使用 revocation_reason: manual 撤销。手动撤销在订阅续订时不自动再次授予。
许可证密钥禁用	对于许可证密钥授予，禁用基础密钥会使用 revocation_reason: license_key_disabled 撤销授予。如果密钥被重新启用，授予会自动重新激活。
平台漂移检测	如果集成的平台一侧不同步（Discord角色被手动删除、GitHub App失去仓库访问或对缺失目标的对账结果），授予会使用 revocation_reason: platform_external 撤销。在订阅续订时不自动再次授予，直到解决平台底层问题。

订阅驱动的授予为每个 (entitlement, customer, subscription) 幂等；续订和重新激活不会创建重复的授予。一时间授予对于每个 (entitlement, customer, payment) 也是幂等的。

---

​

创建您的第一个权限

1. Open Entitlements

   在您的Dodo Payments仪表板中转到权限并单击**+**创建一个新的权限。

2. Pick an integration

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

3. Configure delivery

   填写集成特定的字段。例如，GitHub要求提供仓库和权限级别；Discord要求提供服务器和可选角色；许可证密钥要求提供激活限制和到期时间。

   

   Creating a GitHub entitlement. Each integration shows the fields it needs.

4. Save

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

​

将权限附加到产品上

打开一个产品，展开高级设置 → 权限和信用，选择产品购买时应交付的权限。一个产品可以一次交付多个权限。例如，一个Pro计划可以包括许可证密钥、GitHub访问和Discord角色。

Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.

---

​

客户体验

​

电子邮件和客户门户

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

​

基于OAuth的交付

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

​

撤销

撤销的授予在平台级别被移除：Discord角色被移除，GitHub协作者被移除，许可证密钥被禁用。客户可以在客户门户中看到更改的反映。

对于数字文件，撤销会阻止继续访问预签名URL，但不会使客户已经下载的副本失效。计划内容时请相应考虑。

---

​

管理授予

从仪表板打开任何权限以查看其授予。授予详细信息面板显示总授予数、状态筛选器、客户信息、交付日期和撤销操作。

您还可以通过编程方式管理授予：

TypeScript

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事件。订阅这些事件以使您的应用程序与每个客户可以访问的内容保持同步。

事件	触发时
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 撤销是有意的。在客户沟通中要区别对待。