手動ライセンスキー発行統合ガイド

このガイドでは、手動ライセンスキー付与システムを最初から最後まで構築する方法を説明します。Dodo Payments が支払い時にキーを自動生成する代わりに、購入ごとに Pending grant が作成され、ユーザー自身のシステム、サードパーティベンダー、または有限のコードプールからキー値を提供するまで待機します。完了することで、次のことが可能になります:

ライセンスキー権利が manual 発行に設定された製品。
顧客がキーを待っているときに検出する Webhook リスナー。
キーを配信し、顧客に自動的に通知する発行コール。

License Keys overview

完全なライセンスキーライフサイクルと fulfillment_mode 設定。

Fulfill License Key Grant API

キーを配信するために呼び出すエンドポイントの API リファレンス。

仕組み

手動発行では、発行ステップだけが変更されます。配信された後は、アクティベーション、検証、無効化、有効期限、取り消しは自動生成されたキーと同じように動作します。

前提条件

このガイドを進めるには次のものが必要です:

Dodo Payments マーチャントアカウント。
ダッシュボードの API キー (DODO_PAYMENTS_API_KEY) と Webhook シークレットキー。API キー生成ガイドを参照: API key generation guide。
Webhook を受信できるバックエンドエンドポイント。

https://test.dodopayments.com とテストモードの資格情報を使用して構築します。製品に移行するときは https://live.dodopayments.com とライブキーに切り替えてください。

ステップ 1 — 手動モードでライセンスキー権利を作成

権利とは、提供するものの再利用可能な定義です。ライセンスキー権利を作成し、その fulfillment_mode を manual に設定します。

Dashboard
API

Open Entitlements

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

Choose License Key

ライセンスキーを統合として選択し、名前を付けます。フォームは次のフィールドを公開しています:

Fulfillment Mode — デフォルトでは Automatic。これは手動発行を有効にする設定です。次のステップで変更します。
License Length — 各発行されたキーが有効である期間、または No expiration。
Activations Limit — 各キーの最大アクティベーション数、または Unlimited。
Activation Message — キーを有効化するときに表示される、顧客向けのオプションメッセージ。

名前、付与モード、ライセンス期間、アクティベーション上限、アクティベーションメッセージを含む新しいライセンスキー entitlement フォーム

Set Fulfillment Mode to Manual

Fulfillment Mode ドロップダウンを開き、Automatic から Manual に変更します。これがこのガイド全体を左右する設定です。この設定を行わない場合、キーが自動的に生成されてメールで送信され、保留中の grant は作成されません。Manual を選択すると、購入ごとに付与対象の Pending grant が作成されます。Create Entitlement をクリックして保存します。

権利を integration_config.fulfillment_mode を manual に設定して作成します。

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const entitlement = await client.entitlements.create({
  name: 'Pro License (Manual)',
  integration_type: 'license_key',
  integration_config: {
    fulfillment_mode: 'manual',
    activations_limit: 5,
    duration_count: 1,
    duration_interval: 'Year',
  },
});

console.log(entitlement.id); // ent_...

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

entitlement = client.entitlements.create(
    name="Pro License (Manual)",
    integration_type="license_key",
    integration_config={
        "fulfillment_mode": "manual",
        "activations_limit": 5,
        "duration_count": 1,
        "duration_interval": "Year",
    },
)

print(entitlement.id)

curl -X POST https://test.dodopayments.com/entitlements \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro License (Manual)",
    "integration_type": "license_key",
    "integration_config": {
      "fulfillment_mode": "manual",
      "activations_limit": 5,
      "duration_count": 1,
      "duration_interval": "Year"
    }
  }'

fulfillment_mode はデフォルトで auto です。それを省略するか、既存の権利を変更しないままでいると、自動動作が維持されます。明示的に manual に設定された権利のみが保留中の付与を作成します。

ステップ 2 — 権利を製品に添付

販売したい製品を開き、詳細設定 → 権利 & クレジットを展開し、ステップ 1 で手動に設定したライセンスキー権利を選択します。単一の製品で、このライセンスキーを他の権利と同じ購入に一緒に提供することができます。

製品権利パネルにライセンスキーが選択されている — Selecting the License Key entitlement in the product entitlements panel.

発行モードは権利のプロパティであり、製品のプロパティではありません。ステップ 1 で手動に設定したので、この権利が添付されたすべての製品は購買時に pending ライセンスキーの付与を作成します—ここでは何も追加で設定する必要はありません。

付与モードは product ではなく entitlement のプロパティです。Step 1 で Manual に設定したため、この entitlement が関連付けられたすべての product では、購入時に Pending license-key grant が作成されます。ここで追加設定を行う必要はありません。

ステップ 3 — 保留中の付与を検出

顧客が製品を購入すると、Dodo Payments は pending 状態でキーが添付されていない付与を作成し、entitlement_grant.created Webhook を発火します。これが顧客がキーを待っていることを示す合図です。顧客が product を購入すると、Dodo Payments はキーが添付されていない状態で Pending status の grant を作成し、entitlement_grant.created webhook を発火します。これは、顧客がキーを待っていることを示すシグナルです。 Webhook エンドポイントをセットアップし (ダッシュボードの Developer → Webhooks)、保留中のライセンスキー付与にアクションを起こします。実装は Standard Webhooks の仕様に従います。

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'pending'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'Pending'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

または List Grants API をポーリングする

Webhook に頼りたくない場合は、権利のために付与をリストし、integration_type と status でフィルタリングします: Webhook に依存したくない場合、ライセンスキーの承認のための付与を一覧表示し、status でフィルタリングしてください。ライセンスキーの承認に関するすべての付与はすでにライセンスキーの付与であるため、integration_type フィルタは不要です。

Node.js

const pending = await client.entitlements.grants.list('ent_license_key_id', {
  integration_type: 'license_key',
  status: 'pending',
});

for (const grant of pending.items) {
  console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
}

Node.js

const pending = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'Pending',
});

for (const grant of pending.items) {
  console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
}

cURL

curl -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  --data-urlencode "status=Pending"

ステップ 4 — キーを配信

独自のシステムからキーの値を取得し、Fulfill License Key Grant エンドポイントに送信します。これには秘密の API キー (編集者権限) が必要です。これは公開ライセンスエンドポイントのひとつではありません。

async function fulfill(grantId: string, key: string) {
  const res = await fetch(
    `https://test.dodopayments.com/grants/${grantId}/license-key`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      },
      body: JSON.stringify({
        key,
        // Optional — fall back to the entitlement config when omitted
        activations_limit: 5,
        expires_at: '2027-05-01T00:00:00Z',
      }),
    },
  );

  if (!res.ok) {
    // See the status code table below for handling
    throw new Error(`Fulfillment failed: ${res.status}`);
  }

  return res.json(); // updated grant, now status: "delivered"
}

async function fulfill(grantId: string, key: string) {
  const res = await fetch(
    `https://test.dodopayments.com/grants/${grantId}/license-key`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      },
      body: JSON.stringify({
        key,
        // Optional — fall back to the entitlement config when omitted
        activations_limit: 5,
        expires_at: '2027-05-01T00:00:00Z',
      }),
    },
  );

  if (!res.ok) {
    // See the status code table below for handling
    throw new Error(`Fulfillment failed: ${res.status}`);
  }

  return res.json(); // updated grant, now status: "Delivered"
}

リクエストフィールド

string

必須

顧客に配信するためのライセンスキー文字列。空白がトリムされます。空または空白のみの値は拒否されます。

integer

キーごとのアクティベーション制限。省略時は権利の設定にフォールバックします。

string

キーごとの有効期限 (ISO 8601)。省略時は権利設定の期間にフォールバックします。サブスクリプション発行の付与の場合、有効性はサブスクリプションに関係なくつながれたままです。

成功すれば付与が delivered に移行し、顧客に自動的にキーが送信されます（自動発行の下で受け取るのと同じメール）、entitlement_grant.delivered が発火します。成功すると grant は Delivered に移行し、顧客にはキーが自動的に送信されます（自動付与の場合に受け取るものと同じメールです）。さらに、license_key.created と entitlement_grant.delivered webhook event が発火します。

ライセンスキー、製品、アクティベーション制限、有効期限、アクティベーション指示を示す顧客ライセンスキーのメール — The license key email the customer receives once you fulfill the grant.

キーを自分でメール送信する必要はありません—付与が完了すると自動的に配信されます。

ステップ 5 — エラーと再試行の処理

エンドポイントは何も配信する前に付与を検証します。次の応答を処理します:

ステータス	意味	すべきこと
`200`	キーが配信され、付与は現在 `delivered` です。	完了。
`400`	ライセンスキーの付与ではない、またはキーが空/空白。	リクエストを修正し、そのまま再試行しないでください。
`404`	ビジネスにその ID の付与は存在しません。	`grant_id` を確認します。
`409`	付与は発行待ちでない（すでに配信されているか、すでにキーがある）、またはキー値がすでに存在します。	すでに配信されている場合は、成功として処理します。重複したキーの場合は、別のキーを提供してください。
`422`	リクエスト本文のバリデーションに失敗した（例: `activations_limit < 1`）。	フィールドを修正して再試行してください。

Status	Meaning	What to do
`200`	キーが配信され、grant は現在 `Delivered` です。	完了です。
`400`	license-key grant ではないか、キーが空または空白のみです。	リクエストを修正してください。そのまま再試行しないでください。
`404`	その ID を持つ grant が business に存在しません。	`grant_id` を確認してください。
`409`	grant が付与を待機していません（すでに配信済み、またはすでにキーがあります）。またはキー値がすでに存在します。	すでに配信済みの場合は成功として扱ってください。キーが重複している場合は、別のキーを指定してください。
`422`	リクエスト body の validation に失敗しました（例：`activations_limit < 1`）。	field を修正して再試行してください。

フローを確認

テストモードで製品を購入 (チェックアウトガイドを参照: checkout guides)。
Webhook で entitlement_grant.created が status: "pending" と integration_type: "license_key" を受信していることを確認、または付与がこれらのフィルタで List Grants の応答に表示されることを確認します。
テストキーで発行エンドポイントを呼び出します。
応答が status: "delivered" を示し、license_key が入力され、顧客がキーのメールを受け取り、entitlement_grant.delivered が発火することを確認します。
test mode で product を購入します（checkout guides を参照してください）。
webhook が entitlement_grant.created を status: "Pending" および integration_type: "license_key" とともに受信したことを確認します。または、同じ filter を指定した List Grants response に grant が表示されることを確認します。
test key を指定して fulfill endpoint を呼び出します。
response に status: "Delivered" と値が設定された license_key が表示され、顧客が key email を受信し、entitlement_grant.delivered が発火することを確認します。

Create Entitlement

fulfillment_mode: manual でライセンスキーの権利を作成します。

List Grants

integration_type と status でフィルターして保留中の付与を見つけます。

Fulfill License Key Grant

キーの値を配信し、付与を配信済みへと移行します。

Entitlement Grant Webhooks

保留中と配信済みの付与を示す entitlement_grant.* イベント。

Create Entitlement

fulfillment_mode: manual を指定して License Key entitlement を作成します。

List Grants

status と customer_id で filter して、保留中の grant を検索します。

Fulfill License Key Grant

キー値を配信し、grant を delivered に移行します。

Entitlement Grant Webhooks

保留中および配信済みの grant を示す entitlement_grant.* event。

Integration Guides

Billing Deconstructions

Cookbooks

手動ライセンスキー発行統合ガイド

License Keys overview

Fulfill License Key Grant API

仕組み

前提条件

ステップ 1 — 手動モードでライセンスキー権利を作成

ステップ 2 — 権利を製品に添付

ステップ 3 — 保留中の付与を検出

または List Grants API をポーリングする

ステップ 4 — キーを配信

リクエストフィールド

ステップ 5 — エラーと再試行の処理

フローを確認

関連 API リファレンス

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys overview

Fulfill License Key Grant API

​仕組み

​前提条件

​ステップ 1 — 手動モードでライセンスキー権利を作成

​ステップ 2 — 権利を製品に添付

​ステップ 3 — 保留中の付与を検出

​または List Grants API をポーリングする

​ステップ 4 — キーを配信

​リクエストフィールド

​ステップ 5 — エラーと再試行の処理

​フローを確認

​関連 API リファレンス

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

仕組み

前提条件

ステップ 1 — 手動モードでライセンスキー権利を作成

ステップ 2 — 権利を製品に添付

ステップ 3 — 保留中の付与を検出

または List Grants API をポーリングする

ステップ 4 — キーを配信

リクエストフィールド

ステップ 5 — エラーと再試行の処理

フローを確認

関連 API リファレンス