介绍 - Dodo Payments Documentation

权限将成功付款或活跃订阅转化为实际访问权限：您的客户邮箱中的许可证密钥、您的应用检测的功能标志、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聊天或频道中。

Framer

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

Notion

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

授予的工作原理

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

授予生命周期

Created

付款完成或订阅变为活跃状态时，会创建一项授予。Feature flags 会直接跳转到 Delivered。当权益使用 fulfillment_mode: auto（默认值）时，License keys 也会直接跳转到 Delivered；在 fulfillment_mode: manual 下，授予会在 Pending 中创建，在你通过 Fulfill License Key Grant 提供密钥之前不会包含密钥。其他所有集成都从 Pending 开始。基于 OAuth 的集成（Discord、GitHub、Notion）会提供一个 oauth_url，客户必须访问该地址才能完成授权；对于新创建的授予，此字段为 null；客户从交付邮件或 Customer Portal 开始接受流程后，该字段会被填充。平台直连集成（Telegram、Framer、Digital Files）只会在交付配置期间短暂处于 Pending，随后转为 Delivered。

Delivered

交付完成后（生成 License Key、分配角色、授予存储库访问权限、解析文件链接或完成 OAuth），授权会转为 Delivered，并设置 delivered_at。

Failed

如果集成调用返回不可重试的错误（OAuth token 被撤销、权限被拒绝或文件不再存在），授权会转为 Failed。error_code 和 error_message 字段会记录原因。

Revoked

当访问权限被撤销时（订阅取消、退款发放或商户发起撤销），授权会转为 Revoked。revocation_reason 字段会记录触发原因。

事件驱动的授予行为

事件	行为
`payment.succeeded`（一次性付款）	为每项附加的权益发放一项授予。
`payment.succeeded`（订阅关联付款）	不执行任何操作。授予由下方的订阅事件驱动。
`subscription.active`	为所有附加但尚未拥有授予的权益发放授予。重新发放此前因同一订阅被撤销的授予。
`subscription.renewed`	不执行任何操作。现有授予会在续订期间持续存在。
`subscription.on_hold`	撤销所有已交付和待处理的授予。`revocation_reason: subscription_on_hold`。
`subscription.paused`	撤销所有已交付和待处理的授予。`revocation_reason: SubscriptionPaused`。
`subscription.unpaused`	重新发放此前因同一订阅被撤销的授予，其行为与 `subscription.active` 完全相同。
`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` 撤销。订阅续订时不会自动重新发放手动撤销的授予。
License key disabled	对于 License key 授予，停用底层密钥会使用 `revocation_reason: license_key_disabled` 撤销该授予。重新启用密钥后，该授予会自动重新激活。
检测到平台状态偏移	如果集成的平台端状态不同步（例如手动移除了 Discord 角色、GitHub App 失去仓库访问权限，或协调检查发现目标缺失），系统会使用 `revocation_reason: platform_external` 撤销该授予。在底层平台问题解决之前，订阅续订时不会自动重新发放。

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

创建您的第一个权限

Open Entitlements

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

Pick an integration

选择集成类型：License Key、Digital Files、Feature Flag、Discord、GitHub、Telegram、Figma、Framer 或 Notion。对于平台集成，如果你尚未连接账户，请先连接。

Configure delivery

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

新权限表格，包含集成选择器和配置字段 — Creating a GitHub entitlement. Each integration shows the fields it needs.

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 向其授予访问权限。在客户通过电子邮件或 Customer Portal 中的链接完成 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('entg_xyz789', {
  id: 'ent_abc123',
});

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

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

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

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

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`	创建新授权时。License-key 授权在 `auto` fulfillment 下以 `Delivered` 到达，在 `manual` fulfillment 下以 `Pending` 到达；其他所有集成均以 `Pending` 到达，并在平台调用成功后转为 `Delivered`（对于基于 OAuth 的集成，则在客户完成授权后转为该状态）。
`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 流程）。请等待 delivered 事件，然后再在你自己的系统中解锁依赖功能。
将 entitlement_grant.failed 视为需要采取行动的事件。 授予失败意味着客户已经付款但未获得访问权限。请将这些情况反馈给支持团队，或触发重新发放。
将 revocation_reason 映射到你的留存流程。 subscription_on_hold 撤销是可恢复的（客户可能会更新其银行卡）。manual 撤销则是有意为之。在客户沟通中应区别对待这两种情况。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

介绍

什么是权限？

可用集成

License Keys

Digital Files

Feature Flags

Discord

GitHub

Telegram

Framer

Notion

授予的工作原理

授予生命周期

事件驱动的授予行为

创建您的第一个权限

将权限附加到产品上

客户体验

电子邮件和客户门户

基于OAuth的交付

撤销

管理授予

API管理

Create Entitlement

List Entitlements

Get Entitlement

Update Entitlement

Delete Entitlement

Upload File

List Grants

Revoke Grant

Webhooks

Entitlement Grant Webhook Payloads

最佳实践

​什么是权限？

​可用集成

License Keys

Digital Files

Feature Flags

Discord

GitHub

Telegram

Framer

Notion

​授予的工作原理

​授予生命周期

​事件驱动的授予行为

​创建您的第一个权限

​将权限附加到产品上

​客户体验

​电子邮件和客户门户

​基于OAuth的交付

​撤销

​管理授予

​API管理

Create Entitlement

List Entitlements

Get Entitlement

Update Entitlement

Delete Entitlement

Upload File

List Grants

Revoke Grant

​Webhooks

Entitlement Grant Webhook Payloads

​最佳实践

什么是权限？

可用集成

授予的工作原理

授予生命周期

事件驱动的授予行为

创建您的第一个权限

将权限附加到产品上

客户体验

电子邮件和客户门户

基于OAuth的交付

撤销

管理授予

API管理

Webhooks

最佳实践