導入 - 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 は grant（1人の顧客に対してそのentitlementを発行したもの）を作成します。Grant はいくつかのステータスを順に遷移します。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

grant は、payment が完了するか、subscription が active になると作成されます。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 がアクセスして consent を完了する必要がある oauth_url が公開されます。新しく作成された grant では、この field は null であり、customer が delivery email または customer portal から accept flow を開始すると設定されます。Platform-direct integration（Telegram、Framer、Digital Files）は、delivery の provision 中だけ短時間 Pending に留まり、その後 Delivered に移行します。

Delivered

配信が完了すると（License keyの生成、ロールの割り当て、リポジトリへのアクセス権の付与、ファイルリンクの解決、OAuthの完了など）、grant は Delivered に遷移し、delivered_at が設定されます。

Failed

integrationの呼び出しが再試行不能なエラー（OAuth tokenの取り消し、権限の拒否、ファイルが存在しなくなった場合など）を返すと、grant は Failed に遷移します。error_code フィールドと error_message フィールドに、その理由が記録されます。

Revoked

アクセスが取り消されると（サブスクリプションのキャンセル、返金の発行、またはmerchantによる取り消しなど）、grant は Revoked に遷移します。revocation_reason フィールドに、そのトリガーが記録されます。

イベントによる権利の動作

Event	Behavior
`payment.succeeded`（one-time payment）	紐付けられた各 entitlement に対して grant を 1 つ発行します。
`payment.succeeded`（subscription-linked payment）	No-op。grant は以下の subscription event によって処理されます。
`subscription.active`	紐付けられた 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) によって冪等です。

最初の権利を作成

Open Entitlements

Dodo Payments ダッシュボードの Entitlements に移動し、+ をクリックして新しい権利を作成します。

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

権利を保存します。これで、任意の商品に添付することができます。

商品に権利を添付

商品を開き、Advanced Settings → Entitlements & Credits を展開し、商品購入時に配信される権利を選択します。単一の商品で複数の権利を同時に配信できます。たとえば、Pro プランには、ライセンスキー、GitHub アクセス、および Discord 役割を含めることができます。

製品権利選択パネルで各権利のチェックボックスを表示 — Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.

顧客体験

Eメールと顧客ポータル

顧客は、購入後に配信メールを受け取り、ライセンスキー、ダウンロードリンク、OAuth 招待リンク、またはプラットフォーム招待など、製品の権利に該当するものが含まれます。同じ情報は、Customer Portal の注文履歴から無期限に利用可能です。

OAuth ベースの配信

Discord、GitHub、Notionのsubscriber accessでは、顧客がDodo Paymentsにアクセス権の付与を承認する必要があります。これらのgrantは、顧客がメールまたはCustomer Portalのリンクを使用してOAuthフローを完了するまで、Pending ステータスのままです。承認が完了すると、grant は Delivered に遷移し、platform accessが直ちにプロビジョニングされます。

取り消し

取り消された権利はプラットフォームレベルで削除されます：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 は、権利のライフサイクルに対して 4 つの webhook イベントを発行します。これらのイベントを購読して、各顧客がアクセスできる内容に関してアプリケーションを同期状態に保ちます。

Event	Fires when
`entitlement_grant.created`	新しいgrantが作成されたとき。License-key grantは、`auto` fulfillmentでは `Delivered` で、`manual` fulfillmentでは `Pending` で到着します。その他のすべてのintegrationは `Pending` で到着し、platform callが成功すると（OAuthベースのintegrationの場合は顧客が承認すると）`Delivered` に遷移します。
`entitlement_grant.delivered`	grantがdeliveredに遷移したとき。顧客はアクセスできるようになります。
`entitlement_grant.failed`	grantを配信できなかったとき。`error_code` と `error_message` を確認してください。
`entitlement_grant.revoked`	アクセスが取り消されたとき。`revocation_reason` を確認してください。

Entitlement Grant Webhook Payloads

完全なペイロードスキーマ、サンプルイベント、および revocation_reason リファレンスを表示します。

ベストプラクティス

delivery channel ごとに entitlement を 1 つ使用します。 異なる role の意図を持つ複数の product 間で 1 つの Discord entitlement を共有しないでください。revoke を明確に行えるよう、role ごとに 1 つ作成します。
まず test mode でテストします。 entitlement を作成して test product に紐付け、checkout を実行し、grant が Pending → Delivered を通じて遷移することを確認します。test subscription をキャンセルすると grant が revoke されることを確認してください。
entitlement_grant.delivered をリッスンし、payment.succeeded は使用しません。 payment は fulfilment が完了する前に成功する可能性があります（特に OAuth flow の場合）。自社 system で依存する feature のロックを解除する前に、delivered event を待ってください。
entitlement_grant.failed を対応が必要なものとして扱います。 failed grant は、customer が支払いを済ませたにもかかわらず access を取得できていないことを意味します。これらを support team に通知するか、regrant を実行してください。
revocation_reason を retention flow にマッピングします。 subscription_on_hold revoke は回復可能です（customer はカードを更新できる場合があります）。manual revoke は意図的なものです。customer との communication では、これらを区別して扱ってください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

導入

特権とは何ですか？

利用可能な統合

License Keys

Digital Files

Feature Flags

Discord

GitHub

Telegram

Framer

Notion

権利のしくみ

権利のライフサイクル

イベントによる権利の動作

最初の権利を作成

商品に権利を添付

顧客体験

Eメールと顧客ポータル

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

​権利のしくみ

​権利のライフサイクル

​イベントによる権利の動作

​最初の権利を作成

​商品に権利を添付

​顧客体験

​Eメールと顧客ポータル

​OAuth ベースの配信

​取り消し

​権利の管理

​API 管理

Create Entitlement

List Entitlements

Get Entitlement

Update Entitlement

Delete Entitlement

Upload File

List Grants

Revoke Grant

​Webhooks

Entitlement Grant Webhook Payloads

​ベストプラクティス

特権とは何ですか？

利用可能な統合

権利のしくみ

権利のライフサイクル

イベントによる権利の動作

最初の権利を作成

商品に権利を添付

顧客体験

Eメールと顧客ポータル

OAuth ベースの配信

取り消し

権利の管理

API 管理

Webhooks

ベストプラクティス