메인 콘텐츠로 건너뛰기

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 저장소에 대한 액세스, 다운로드 가능한 전자책 번들. Dodo Payments는 entitlements를 제품에 연결한 후 나머지를 처리합니다. 고객이 제품을 구매하면 Dodo Payments는 grant를 생성합니다. 이는 해당 entitlement의 단일 고객 발급을 의미합니다. Grant는 상태 변화를 겪습니다: 배송이 진행 중일 때는 pending, 고객이 액세스할 수 있게 되면 delivered, 배송이 완료되지 않을 경우 failed, 액세스가 철회되면 revoked.
Entitlements는 fulfillment(고객이 액세스 가능한가?)를 통제하고, Credits는 consumption(얼마나 사용할 수 있는가?)을 통제합니다. 둘 다 같은 제품에 첨부할 수 있습니다. 크레딧에 대한 자세한 내용은 Credit-Based Billing을 참조하세요.

​
사용 가능한 통합

Dodo Payments는 각 entitlement를 전용 통합을 통해 제공합니다. 판매하는 항목에 맞는 통합을 선택하세요.

License Keys

고유한 라이선스 키를 생성하고 활성화 제한 및 만료를 설정할 수 있습니다. 소프트웨어, 플러그인 및 CLI에 최적입니다.

Digital Files

사전 서명된 다운로드 URL과 선택적 지침을 통해 다운로드 가능한 파일(전자책, 템플릿, 미디어)을 제공합니다.

Discord

고객이 구매했을 때 Discord 서버에 역할을 부여합니다. 취소 시 자동으로 취소합니다.

GitHub

고객을 선택한 권한 수준으로 프라이빗 저장소의 협력자로 추가합니다.

Telegram

고객을 구매 후 개인 Telegram 채팅 또는 채널에 추가합니다.

Framer

결제한 고객을 위해 Framer 템플릿 리믹스 링크를 잠금 해제합니다.

Notion

구매 시 고객의 작업 공간에 Notion 템플릿을 복제합니다.

​
Grants 작동 방식

Grant는 웹훅으로 이미 수신되는 동일한 결제 및 구독 이벤트에 의해 구동됩니다. 구매를 위해 직접 grant API를 호출할 필요가 없습니다. Dodo Payments는 기본 결제 라이프사이클에 따라 grant를 자동으로 생성 및 취소합니다.

​
Grant 라이프사이클

1

Created

결제가 완료되거나 구독이 활성화될 때 grant가 생성됩니다. 라이선스 키는 즉시 delivered로 이동합니다. 다른 모든 통합은 pending에서 시작됩니다. OAuth 기반 통합(Discord, GitHub, Notion)은 고객이 동의를 완료하기 위해 방문해야 하는 oauth_url를 포함합니다. 플랫폼 직접 통합(Telegram, Framer, Digital Files)은 배송이 준비되는 동안 잠깐만 pending에 머물러 있다가 delivered로 전환됩니다.
2

Delivered

배달이 완료되면(라이선스 키 생성, 역할 할당, 저장소 액세스 부여, 파일 링크 해결, OAuth 완료) grant는 delivered로 이동하고 delivered_at가 설정됩니다.
3

Failed

통합 호출이 재시도 불가능한 오류(OAuth 토큰 취소, 권한 거부, 파일이 더 이상 존재하지 않음)를 반환하면 grant는 failed로 이동합니다. error_code 및 error_message 필드는 이유를 캡처합니다.
4

Revoked

접근이 철회되면(구독 취소, 환불 발행 또는 상인 주도 취소) grant는 revoked로 이동합니다. revocation_reason 필드는 트리거를 기록합니다.

​
이벤트별 Grant 동작

이벤트동작
payment.succeeded (단일 결제)연결 된 모든 entitlement에 대해 각 grant를 발급합니다.
payment.succeeded (구독 연결 결제)무작위 동작. Grant는 아래의 구독 이벤트에 의해 구동됩니다.
subscription.active아직 grant가 없는 모든 붙여진 entitlements에 대해 grant를 발급합니다. 동일한 구독의 경우 이전에 취소된 모든 grant를 재허용합니다.
subscription.renewed무작위 동작. 기존 grant는 갱신을 통해 지속됩니다.
subscription.on_hold모든 배달 및 대기 중인 grant를 취소합니다. revocation_reason: subscription_on_hold.
subscription.cancelled모두 취소합니다. revocation_reason: subscription_cancelled.
subscription.expired모두 취소합니다. revocation_reason: subscription_expired.
subscription.plan_changed현재 grant를 모두 취소한 다음, 새 계획의 entitlements에 대한 grant를 발급합니다. revocation_reason: plan_changed.
refund.succeeded (단일 결제)해당 결제에 대한 grant를 취소합니다. revocation_reason: refund.
Manual API revokerevocation_reason: manual로 취소합니다. 수동 취소는 구독 갱신 시 자동으로 재허용되지 않습니다.
License key disabled라이선스 키 grant의 경우, 기본 키를 비활성화하면 revocation_reason: license_key_disabled로 grant가 취소됩니다. 키가 다시 활성화되면 grant는 자동으로 재활성화됩니다.
Platform drift detected통합의 플랫폼 측이 동기화에서 벗어난 경우 (Discord 역할 수동 제거, GitHub 앱이 저장소 액세스를 잃은 상태, 조정 패스가 누락된 대상을 감지하는 경우), grant는 revocation_reason: platform_external로 취소됩니다. 기본적인 플랫폼 문제가 해결되기 전까지는 구독 갱신 시 자동으로 재허용되지 않습니다.
구독 기반 grant는 (entitlement, customer, subscription)마다 멱등성을 가집니다. 갱신 및 재활성화는 중복 grant를 생성하지 않습니다. 단발성 grant는 (entitlement, customer, payment)마다 멱등성을 가집니다.

​
첫 번째 entitlement를 만드세요

1

Open Entitlements

Dodo Payments 대시보드에서 Entitlements로 이동한 후 + 버튼을 클릭하여 새 entitlements를 만드세요.
2

Pick an integration

통합 유형을 선택하세요: License Key, Digital Files, Discord, GitHub, Telegram, Framer, Notion. 플랫폼 통합의 경우, 먼저 계정을 연결하세요.
3

Configure delivery

통합별 필드를 작성하세요. 예를 들어, GitHub는 저장소와 권한 수준을 요청하고, Discord는 서버와 선택적 역할을 요청하며, License Key는 활성화 제한 및 만료를 요청합니다.
통합 선택기 및 구성 필드가 있는 새 Entitlement 양식
4

Save

Entitlement를 저장합니다. 이제 이를 어떤 제품에도 첨부할 수 있습니다.

​
Entitlements를 제품에 첨부하기

제품을 열고, 고급 설정 → Entitlements & Credits를 확장하고, 제품 구매 시 제공할 entitlements를 선택합니다. 단일 제품은 여러 entitlements를 동시에 제공합니다. 예를 들어, Pro 계획은 라이선스 키, GitHub 액세스 및 Discord 역할을 포함할 수 있습니다.
각 가용 entitlement에 대한 체크박스를 표시하는 제품 entitlement 선택 패널

​
고객 경험

​
이메일 및 고객 포털

고객은 구매 후 라이선스 키, 다운로드 링크, OAuth 초대 링크 또는 플랫폼 초대가 포함된 배송 이메일을 수신합니다. 동일한 정보는 주문 내역 아래의 고객 포털에서 무기한으로 확인할 수 있습니다.

​
OAuth 기반 배송

Discord, GitHub, Notion 구독자 액세스는 고객이 Dodo Payments에 액세스를 부여하도록 승인해야 합니다. 이러한 grant는 고객이 이메일 또는 고객 포털의 링크를 사용하여 OAuth 흐름을 완료할 때까지 pending 상태에 머무릅니다. 승인이 완료되면 grant는 delivered로 이동하며 플랫폼 액세스가 즉시 제공됩니다.

​
취소

취소된 grant는 플랫폼 수준에서 제거됩니다: Discord 역할이 제거되고, GitHub 협력자가 제거되고, 라이선스 키가 비활성화됩니다. 고객 포털에 변화가 반영됩니다.
Digital Files의 경우, 취소는 향후 서명된 URL에 대한 액세스를 제거하지만 고객이 이미 다운로드한 사본은 무효화하지 않습니다. 이에 따라 콘텐츠 게이팅을 계획하세요.

​
Grant 관리

대시보드에서 임의의 entitlement를 열어 그에 대한 grants를 확인하세요. grant 세부 패널에서는 전체 grant, 상태 필터, 고객 정보, 배송 날짜 및 취소 작업을 표시합니다. 또한 프로그래밍 방식으로 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

모든 통합 유형의 새 entitlements 생성.

List Entitlements

통합 유형별로 필터링하여 entitlements 나열.

Get Entitlement

Entitlements 및 해석된 구성을 검색합니다.

Update Entitlement

이름, 설명 또는 통합 구성을 업데이트합니다.

Delete Entitlement

Entitlement를 소프트 삭제합니다. 기존 grant는 영향을 받지 않습니다.

Upload File

Digital Files entitlement에 파일 업로드 (최대 100 MB).

List Grants

상태 및 고객 필터를 사용하여 entitlement에 대한 모든 grant를 나열.

Revoke Grant

단일 grant를 수동으로 취소합니다.

​
Webhooks

Dodo Payments는 grant 라이프사이클을 위해 네 개의 웹훅 이벤트를 발생시킵니다. 이러한 이벤트를 구독하여 각 고객이 액세스 가능한 내용을 귀하의 애플리케이션과 동기화하세요.
이벤트발생 시기
entitlement_grant.created새로운 grant가 생성됩니다. 라이선스 키 grant는 delivered으로 도착합니다. 다른 모든 통합은 pending에 도착하며 플랫폼 호출이 성공한 후 delivered으로 전환됩니다(또는 OAuth 기반 통합의 경우 고객이 인증하면).
entitlement_grant.deliveredgrant가 전달됨 상태로 전환됩니다. 고객은 이제 액세스를 갖습니다.
entitlement_grant.failedgrant를 전달할 수 없습니다. 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