고객이 결제할 때 라이선스 키, 다운로드 가능한 파일, 기능 플래그 및 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.
Entitlement는 고객에게 제공하는 항목의 재사용 가능한 정의입니다: Pro 라이선스 키, “Patrons” Discord 역할, 프라이빗 GitHub 저장소에 대한 액세스, 다운로드 가능한 전자책 번들. Dodo Payments는 entitlements를 제품에 연결한 후 나머지를 처리합니다.고객이 제품을 구매하면 Dodo Payments는 grant를 생성합니다. grant는 단일 고객에게 해당 entitlement를 발급한 것입니다. grant는 다음과 같은 몇 가지 상태를 거칩니다. 배송이 진행 중일 때는 Pending, 고객이 액세스 권한을 얻으면 Delivered, 배송을 완료할 수 없으면 Failed, 액세스 권한이 철회되면 Revoked입니다.
Entitlements는 fulfillment(고객이 액세스 가능한가?)를 통제하고, Credits는 consumption(얼마나 사용할 수 있는가?)을 통제합니다. 둘 다 같은 제품에 첨부할 수 있습니다. 크레딧에 대한 자세한 내용은 Credit-Based Billing을 참조하세요.
결제 완료 또는 subscription 활성화 시 grant가 생성됩니다. Feature flags는 Delivered로 바로 이동합니다. entitlement가 fulfillment_mode: auto(기본값)를 사용하는 경우 License keys도 Delivered로 바로 이동합니다. fulfillment_mode: manual에서는 grant가 Pending에서 생성되며, Fulfill License Key Grant를 통해 키를 제공할 때까지 키가 없습니다. 다른 모든 integration은 Pending에서 시작합니다. OAuth 기반 integration(Discord, GitHub, Notion)은 customer가 방문하여 동의를 완료해야 하는 oauth_url를 노출합니다. 새로 생성된 grant에서는 이 필드가 null이며, customer가 delivery email 또는 customer portal에서 accept flow를 시작하면 값이 채워집니다. Platform-direct integration(Telegram, Framer, Digital Files)은 delivery가 provision되는 짧은 동안만 Pending에 머문 후 Delivered로 전환됩니다.
integration 호출에서 재시도할 수 없는 오류가 반환되면(철회된 OAuth token, 거부된 permission, 더 이상 존재하지 않는 file) grant는 Failed로 전환됩니다. error_code 및 error_message 필드에 그 이유가 기록됩니다.
4
Revoked
액세스 권한이 철회되면(subscription이 취소되거나, refund가 발행되거나, merchant가 철회를 시작한 경우) grant는 Revoked로 전환됩니다. revocation_reason 필드에 해당 트리거가 기록됩니다.
연결된 entitlement 중 아직 grant가 없는 항목에 대해 grant를 발급합니다. 동일한 subscription에 대해 이전에 revoke된 grant는 다시 발급합니다.
subscription.renewed
No-op입니다. 기존 grant는 renewal 동안 유지됩니다.
subscription.on_hold
delivered 및 pending 상태의 모든 grant를 revoke합니다. revocation_reason: subscription_on_hold.
subscription.paused
delivered 및 pending 상태의 모든 grant를 revoke합니다. revocation_reason: SubscriptionPaused.
subscription.unpaused
subscription.active와 동일하게, 동일한 subscription에 대해 이전에 revoke된 grant를 다시 발급합니다.
subscription.cancelled
모두 revoke합니다. revocation_reason: subscription_cancelled.
subscription.expired
모두 revoke합니다. revocation_reason: subscription_expired.
subscription.plan_changed
현재 grant를 모두 revoke한 후 새 plan의 entitlement에 대한 grant를 발급합니다. revocation_reason: plan_changed.
refund.succeeded (one-time payment)
해당 payment의 grant를 revoke합니다. revocation_reason: refund.
Manual API revoke
revocation_reason: manual를 사용하여 revoke합니다. Manual revoke는 subscription renewal 시 자동으로 다시 발급되지 않습니다.
License key disabled
License-key grant의 경우, 기반 key를 비활성화하면 revocation_reason: license_key_disabled와 함께 grant가 revoke됩니다. key를 다시 활성화하면 grant는 자동으로 재활성화됩니다.
Platform drift detected
integration의 platform 측 상태가 동기화 상태에서 벗어나면(Discord role이 수동으로 제거되거나, GitHub App이 repository access를 잃거나, reconciliation pass에서 target 누락을 감지하는 경우) revocation_reason: platform_external와 함께 grant가 revoke됩니다. 기반 platform 문제가 해결될 때까지 subscription renewal 시 자동으로 다시 발급되지 않습니다.
구독 기반 승인은 (entitlement, customer, subscription)마다 비절개적입니다; 갱신 및 재활성화로 인해 중복 승인이 생성되지 않습니다. 일회성 승인은 (entitlement, customer, payment)마다 비절개적입니다.
대시보드에서 자격을 열면 해당 승인들을 볼 수 있습니다. 승인 세부 정보 패널에는 총 승인 수, 상태 필터, 고객 정보, 전달 날짜, 및 취소 조치가 표시됩니다.승인을 프로그래밍 방식으로 관리할 수 있습니다:
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는 승인 생명주기에 대해 네 개의 웹후크 이벤트를 발생시킵니다. 이 이벤트에 가입하여 각 고객이 접근할 수 있는 내용을 애플리케이션과 동기화하세요.
Event
실행 시점
entitlement_grant.created
새 grant가 생성될 때 실행됩니다. License-key grant는 auto fulfillment에서 Delivered로 도착하고, manual fulfillment에서는 Pending로 도착합니다. 그 외 모든 integration은 Pending로 도착하며, platform 호출이 성공하면(또는 OAuth 기반 integration의 경우 고객이 승인하면) Delivered로 전환됩니다.
entitlement_grant.delivered
grant가 delivered로 전환될 때 실행됩니다. 이제 고객이 액세스할 수 있습니다.
entitlement_grant.failed
grant를 delivered할 수 없을 때 실행됩니다. error_code 및 error_message를 확인하세요.
각 delivery channel마다 entitlement 하나를 사용하세요. 서로 다른 role 의도를 가진 product 간에 하나의 Discord entitlement를 공유하지 마세요. 깔끔한 revoke를 위해 role마다 하나씩 생성하세요.
먼저 test mode에서 테스트하세요. entitlement를 생성하고, test product에 연결한 다음 checkout을 실행하여 grant가 Pending → Delivered를 거쳐 전환되는 과정을 확인하세요. test subscription을 취소하면 grant가 revoke되는지 확인하세요.
entitlement_grant.delivered를 수신하고 payment.succeeded는 수신하지 마세요. 특히 OAuth flow에서는 fulfilment가 완료되기 전에 payment가 성공할 수 있습니다. 자체 시스템에서 종속 기능을 unlock하기 전에 delivered event를 기다리세요.
entitlement_grant.failed를 조치가 필요한 상태로 처리하세요. failed grant는 customer가 비용을 지불했지만 access를 받지 못했다는 의미입니다. 이를 support team에 전달하거나 regrant를 trigger하세요.
revocation_reason를 retention flow에 매핑하세요.subscription_on_hold revoke는 복구할 수 있습니다(customer가 card를 업데이트할 수 있음). manual revoke는 의도적인 동작입니다. customer comms에서 두 경우를 다르게 처리하세요.
