跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Entitlements 将成功付款或活跃订阅转化为实际访问权限：客户收件箱中的许可证密钥、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和可选说明交付可下载文件（电子书、模板、媒体）。

Discord

客户购买后，为他们在您的Discord服务器上授予角色。取消时自动撤销。

GitHub

将客户添加为私人存储库的协作者，权限级别由您选择。

Telegram

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

Framer

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

Notion

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

​
Grants如何工作

Grants是通过您已经接收的webhooks进行的支付和订阅事件驱动的。您无需为购买调用grant API。Dodo Payments 会根据基础支付生命周期自动创建和撤销 grants。

​
Grant 生命周期

1

Created

支付完成或订阅激活时会创建grant。许可证密钥直接跳至delivered。其他集成在pending开始。基于OAuth的集成（Discord，GitHub，Notion）包括客户须访问以完成同意的oauth_url。平台直接集成（Telegram，Framer，数字文件）仅在交付准备好时短暂处于pending，然后过渡到delivered。
2

Delivered

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

Failed

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

Revoked

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

​
Event 对Grant的行为

EventBehavior
payment.succeeded (one-time payment)为每个附加的entitlement发放一个grant。
payment.succeeded (subscription-linked payment)无操作。Grants由以下订阅事件驱动。
subscription.active对于任何没有grant的附加entitlements发放grants。重新授予以前为相同订阅撤销的grants。
subscription.renewed无操作。现有的grants在续订时持续存在。
subscription.on_hold撤销所有已交付和待处理的grants。revocation_reason: subscription_on_hold。
subscription.cancelled撤销所有。revocation_reason: subscription_cancelled。
subscription.expired撤销所有。revocation_reason: subscription_expired。
subscription.plan_changed撤销所有当前的grants，然后为新计划的entitlements发放grants。revocation_reason: plan_changed。
refund.succeeded (one-time payment)撤销该付款的grants。revocation_reason: refund。
Manual API revoke撤销使用revocation_reason: manual。手动撤销不会在订阅续订时自动重新授予。
License key disabled对于许可证密钥grants，禁用基础密钥会使用revocation_reason: license_key_disabled撤销grant。如果密钥被重新启用，grant会自动重新激活。
Platform drift detected如果集成的平台端脱离同步（手动移除Discord角色、GitHub应用程序失去存储库访问权限，或对账通过检测到丢失目标），grant会使用revocation_reason: platform_external撤销。在订阅续订时不自动重新授予，直到解决基础平台问题为止。
基于订阅驱动的grants在每个(entitlement, customer, subscription) 是幂等的；续订和重新激活不会创建重复的grants。一次性grants在每个(entitlement, customer, payment) 是幂等的。

​
创建您的第一个entitlement

1

Open Entitlements

进入您的Dodo Payments仪表板中的Entitlements，然后点击**+**创建一个新的entitlement。
2

Pick an integration

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

Configure delivery

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

Save

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

​
将Entitlements附加到产品

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

​
客户体验

​
电子邮件和客户门户

客户在购买后会收到交付电子邮件，其中包含许可证密钥、下载链接、OAuth邀请链接或平台邀请，具体取决于产品上的entitlements。同样的详细信息可在其订单历史中的客户门户中无限期访问。

​
基于OAuth的交付

Discord、GitHub和Notion 订阅者访问需要客户授权Dodo Payments授予他们访问权限。这些grants会保持在pending状态，直到客户使用其电子邮件或客户门户中的链接完成OAuth流。授权后，grant 移动到delivered，平台访问立即提供。

​
撤销

撤销的grants在平台级别被移除：Discord角色被移除，GitHub协作者被移除，许可证密钥被禁用。客户可在客户门户中反映的更改中看到。
对于数字文件，撤销会移除对预签名URL的未来访问，但不会使客户已下载的副本失效。相应地计划内容的访问。

​
管理Grants

从仪表板中打开任何entitlement以查看其grants。grant详细信息面板显示总grants、状态过滤器、客户信息、交付日期和撤销操作。 您还可以以编程方式管理grants： 
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', {
  path_id: 'ent_abc123',
});

​
API管理

Create Entitlement

创建任何集成类型的新entitlement。

List Entitlements

通过集成类型筛选列出entitlements。

Get Entitlement

检索一个entitlement及其已解决的配置。

Update Entitlement

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

Delete Entitlement

软删除一个entitlement；现有的grants不受影响。

Upload File

上传文件到数字文件entitlement（最大100 MB）。

List Grants

列出一个entitlement的所有grants，带有状态和客户过滤器。

Revoke Grant

手动撤销单个grant。

​
Webhooks

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

Entitlement Grant Webhook Payloads

查看完整的负载模式、示例事件和revocation_reason 引用。

​
最佳实践

  • 为每个交付渠道使用一个entitlement。 不要为具有不同角色意图的产品共享单个Discord entitlement；为每个角色创建一个以便于撤销。
  • 先在测试模式中测试。 创建entitlement，将其附加到测试产品，运行结账，并观察grant在pending → delivered期间的过渡。确认取消测试订阅是否撤销了grant。
  • 监听entitlement_grant.delivered，而不是payment.succeeded。 一次付款可以在完整过程完成之前成功（尤其是对于OAuth流程）。在交付事件发生之前，不要解锁您自己系统中的依赖功能。
  • 将entitlement_grant.failed视为可操作的。 如果grant失败，表示客户付款但没有获得访问权限。将这些信息发送给您的支持团队或触发再授权。
  • 将revocation_reason映射到您的留存流程。 subscription_on_hold 撤销是可恢复的（客户可能会更新他们的卡）。manual 撤销是有意的。在客户通信中区别对待它们。
Last modified on May 14, 2026