Tự động cung cấp khóa giấy phép, tệp tải về, cờ tính năng, và truy cập vào các nền tảng như Discord, GitHub, Telegram, Framer, và Notion khi khách hàng thanh toán.
Entitlements biến một lần thanh toán thành công hoặc đăng ký hoạt động thành quyền truy cập thực tế: một khóa giấy phép trong hộp thư của khách hàng, một cờ tính năng ứng dụng của bạn kiểm tra, một vai trò Discord, một kho lưu trữ GitHub, một mẫu Notion, một liên kết remix Framer, một lời mời trò chuyện Telegram, hoặc một gói tệp tải về. Dodo Payments tự động phát hành, theo dõi và thu hồi quyền truy cập đó khi vòng đời thanh toán thay đổi.
The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.
Một entitlement là một định nghĩa tái sử dụng của thứ bạn cung cấp cho khách hàng: một mã giấy phép Pro, một vai trò “Patrons” trên Discord, quyền truy cập vào kho lưu trữ GitHub riêng của bạn, một gói e-book có thể tải xuống. Bạn gắn entitlements vào sản phẩm, và Dodo Payments xử lý phần còn lại.Khi khách hàng mua sản phẩm, Dodo Payments tạo một grant, tức một lần cấp entitlement cho một khách hàng cụ thể. Grant đi qua một tập hợp nhỏ các trạng thái: Pending khi quá trình phân phối đang diễn ra, Delivered sau khi khách hàng có quyền truy cập, Failed nếu không thể hoàn tất việc phân phối và Revoked khi quyền truy cập bị thu hồi.
Entitlements kiểm soát fulfillment (khách hàng có quyền truy cập không?). Credits kiểm soát consumption (họ có thể sử dụng bao nhiêu?). Cả hai có thể được gắn vào cùng một sản phẩm. Xem Thanh toán Dựa trên Tín dụng cho thông tin về credits.
Grants được điều khiển bởi các sự kiện thanh toán và đăng ký mà bạn đã nhận được dưới dạng webhooks. Bạn không cần phải tự gọi API grant cho các lần mua. Dodo Payments tự động tạo và thu hồi grants dựa trên vòng đời thanh toán cơ bản.
Grant được tạo khi một payment hoàn tất hoặc một subscription trở nên active. Feature flags chuyển thẳng sang Delivered. License keys cũng chuyển thẳng sang Delivered khi entitlement sử dụng fulfillment_mode: auto (mặc định); với fulfillment_mode: manual, grant được tạo ở Pending mà chưa có key cho đến khi bạn cung cấp một key thông qua Fulfill License Key Grant. Mọi integration khác đều bắt đầu ở Pending. Các integration dựa trên OAuth (Discord, GitHub, Notion) cung cấp một oauth_url mà customer phải truy cập để hoàn tất consent; field này là null trên grant mới được tạo và được điền khi customer bắt đầu accept flow từ email delivery hoặc customer portal của họ. Các integration trực tiếp với platform (Telegram, Framer, Digital Files) chỉ ở Pending trong thời gian ngắn khi delivery được provision, sau đó chuyển sang Delivered.
2
Delivered
Sau khi việc phân phối hoàn tất (license key được tạo, role được gán, quyền truy cập repository được cấp, các liên kết tệp được xác định và OAuth hoàn tất), grant chuyển sang Delivered và delivered_at được thiết lập.
3
Failed
Nếu lệnh gọi integration trả về lỗi không thể retry (OAuth token bị thu hồi, quyền bị từ chối hoặc tệp không còn tồn tại), grant chuyển sang Failed. Các field error_code và error_message ghi nhận lý do.
4
Revoked
Khi quyền truy cập bị thu hồi (subscription bị hủy, khoản hoàn tiền được phát hành hoặc merchant chủ động thu hồi), grant chuyển sang Revoked. Field revocation_reason ghi nhận nguyên nhân.
Revoke tất cả grant hiện tại, sau đó cấp grant cho các entitlement của plan mới. revocation_reason: plan_changed.
refund.succeeded (one-time payment)
Revoke grant cho payment đó. revocation_reason: refund.
Manual API revoke
Revoke bằng revocation_reason: manual. Các lần revoke thủ công không được tự động cấp lại khi subscription renewal.
License key disabled
Đối với grant sử dụng license key, việc vô hiệu hóa key nền tảng sẽ revoke grant bằng revocation_reason: license_key_disabled. Grant được tự động kích hoạt lại nếu key được bật lại.
Platform drift detected
Nếu phía platform của một integration bị lệch trạng thái (một Discord role bị xóa thủ công, GitHub App mất quyền truy cập repository hoặc một reconciliation pass phát hiện target bị thiếu), grant sẽ bị revoke bằng revocation_reason: platform_external. Grant không được tự động cấp lại khi subscription renewal cho đến khi vấn đề trên platform nền tảng được giải quyết.
Grants dựa trên đăng ký là idempotent cho mỗi (entitlement, customer, subscription); gia hạn và kích hoạt lại không tạo ra grants trùng lặp. Grants một lần là idempotent cho mỗi (entitlement, customer, payment).
Đi tới Entitlements trong bảng điều khiển Dodo Payments của bạn và nhấp vào + để tạo một quyền lợi mới.
2
Pick an integration
Chọn loại tích hợp: Khóa giấy phép, Tệp kỹ thuật số, Cờ tính năng, Discord, GitHub, Telegram, Figma, Framer hoặc Notion. Đối với các tích hợp nền tảng, trước tiên hãy kết nối tài khoản của bạn nếu bạn chưa thực hiện.
3
Configure delivery
Điền vào các trường cụ thể cho tích hợp. Ví dụ, GitHub yêu cầu kho lưu trữ và mức quyền; Discord yêu cầu máy chủ và vai trò tùy chọn; Khóa giấy phép yêu cầu hạn mức kích hoạt và ngày hết hạn.
Creating a GitHub entitlement. Each integration shows the fields it needs.
4
Save
Lưu quyền lợi. Bây giờ bạn có thể đính kèm nó vào bất kỳ sản phẩm nào.
Mở một sản phẩm, mở rộng Cài đặt nâng cao → Quyền lợi & Tín dụng, và chọn các quyền lợi mà nên được cung cấp khi sản phẩm được mua. Một sản phẩm có thể cung cấp nhiều quyền lợi cùng một lúc. Ví dụ, một kế hoạch Pro có thể bao gồm một khóa giấy phép, quyền truy cập GitHub, và một vai trò Discord.
Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.
Khách hàng nhận được một email cung cấp sau khi mua chứa khóa giấy phép, liên kết tải về, liên kết mời OAuth, hoặc lời mời nền tảng, tùy theo các quyền lợi trên sản phẩm. Các chi tiết này vẫn có sẵn vô thời hạn từ Cổng thông tin Khách hàng dưới lịch sử đơn hàng của họ.
Quyền truy cập subscriber trên Discord, GitHub và Notion yêu cầu khách hàng ủy quyền cho Dodo Payments cấp quyền truy cập cho họ. Các grant này giữ ở trạng thái Pending cho đến khi khách hàng hoàn tất OAuth flow bằng liên kết trong email hoặc customer portal của họ. Sau khi ủy quyền, grant chuyển sang Delivered và quyền truy cập platform được cấp ngay lập tức.
Các grants bị thu hồi được loại bỏ ở cấp độ nền tảng: vai trò Discord bị loại bỏ, cộng tác viên GitHub bị loại bỏ, khóa giấy phép bị vô hiệu hóa. Khách hàng nhìn thấy sự thay đổi được phản ánh trong cổng thông tin khách hàng.
Đối với Tệp Kỹ Thuật Số, việc thu hồi loại bỏ quyền truy cập vào các URL được định sẵn trong tương lai nhưng không làm vô hiệu hóa các bản sao mà khách hàng đã tải xuống. Đặt nội dung kế hoạch tương ứng.
Mở bất kỳ quyền lợi nào từ bảng điều khiển để xem các grants của nó. Bảng chi tiết grant hiển thị tổng số grants, bộ lọc trạng thái, thông tin khách hàng, ngày cung cấp, và hành động thu hồi.Bạn cũng có thể quản lý grants bằng chương trình:
import DodoPayments from 'dodopayments';const client = new DodoPayments({ bearerToken: process.env['DODO_PAYMENTS_API_KEY'],});// List grants for an entitlementconst grants = await client.entitlements.grants.list('ent_abc123', { status: 'Delivered',});// Revoke a single grantawait client.entitlements.grants.revoke('entg_xyz789', { id: 'ent_abc123',});
Dodo Payments phát bốn sự kiện webhook cho vòng đời grant. Đăng ký các sự kiện này để giữ cho ứng dụng của bạn đồng bộ với những gì mỗi khách hàng có thể truy cập.
Sự kiện
Kích hoạt khi
entitlement_grant.created
Một grant mới được tạo. Các grant dạng license-key có trạng thái Delivered với quy trình fulfillment auto và Pending với quy trình fulfillment manual; mọi integration khác có trạng thái Pending và chuyển sang Delivered sau khi lệnh gọi platform thành công (hoặc, đối với các integration dựa trên OAuth, sau khi khách hàng ủy quyền).
entitlement_grant.delivered
Grant chuyển sang trạng thái đã phân phối. Khách hàng hiện đã có quyền truy cập.
entitlement_grant.failed
Không thể phân phối grant. Kiểm tra error_code và error_message.
entitlement_grant.revoked
Quyền truy cập đã bị thu hồi. Kiểm tra revocation_reason.
Entitlement Grant Webhook Payloads
Xem toàn bộ sơ đồ tải, các sự kiện mẫu, và tham chiếu revocation_reason.
Sử dụng một entitlement cho mỗi delivery channel. Không dùng chung một Discord entitlement cho các product có mục đích role khác nhau; hãy tạo một entitlement cho mỗi role để việc revoke rõ ràng.
Trước tiên hãy test ở test mode. Tạo entitlement, đính kèm entitlement đó vào một test product, thực hiện checkout và theo dõi quá trình chuyển đổi của grant qua Pending → Delivered. Xác nhận rằng việc hủy test subscription sẽ revoke grant.
Lắng nghe entitlement_grant.delivered, không phải payment.succeeded. Một payment có thể thành công trước khi fulfilment hoàn tất (đặc biệt với các OAuth flow). Hãy đợi event delivered trước khi mở khóa các feature phụ thuộc trong hệ thống của bạn.
Xem entitlement_grant.failed là một trạng thái cần xử lý. Grant thất bại có nghĩa là customer đã thanh toán nhưng chưa được cấp quyền truy cập. Hãy chuyển các trường hợp này đến team hỗ trợ hoặc trigger việc cấp lại grant.
Map revocation_reason vào các retention flow của bạn. Một lần revoke subscription_on_hold có thể khôi phục (customer có thể cập nhật card của họ). Một lần revoke manual là có chủ đích. Hãy xử lý chúng khác nhau trong hoạt động giao tiếp với customer.
