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

手動ライセンスキー fulfillment では、購入ごとに Pending grant が作成されます。この grant は、Dodo Payments が支払い時にキーを生成する代わりに、あなたがキーの値を提供するまで待機します。キーは、自社システム、サードパーティベンダー、または限られたコードプールから取得できます。このガイドを完了すると、次のことができるようになります。

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

License Keys Overview

完全なライセンスキーのライフサイクルと、fulfillment_mode 設定を理解できます。

Fulfill License Key Grant API

キーを提供するために呼び出す endpoint の API reference を確認できます。

仕組み

以下のシーケンスは、checkout からキーの提供まで、1 回の購入の流れを示しています。手動 fulfillment によって変わるのは issuance のステップだけです。提供後のキーは、activation、validation、deactivation、expiry、revocation について、自動生成されたキーと同じように動作します。複数ユニットの購入では、ユニットごとに 1 つの Pending grant が作成され、各 grant に固有のキーが必要です。

前提条件

このガイドに従うには、次のものが必要です。

Dodo Payments の merchant account。
Developer → API Keys で作成し、DODO_PAYMENTS_API_KEY に保存した API key と、Developer → Webhooks から取得して DODO_PAYMENTS_WEBHOOK_KEY に保存した webhook signing secret。API key generation guideを参照してください。
Webhook を受信できる backend endpoint。

構築中は https://test.dodopayments.com と test mode の認証情報を使用してください。本番環境に移行する際は、https://live.dodopayments.com と live mode のキーに切り替えます。

Step 1 — Manual Mode で License Key Entitlement を作成する

entitlement は、提供するものを定義した再利用可能な定義です。License Key entitlement を作成し、fulfillment_mode を manual に設定します。

Dashboard
API

Open Entitlements

Dashboard で Entitlements に移動し、+ をクリックして entitlement を作成します。

Choose License Key

License Keys を選択し、Name を入力します。フォームには次のフィールドがあります。

Fulfillment Mode: デフォルトは Automatic です。これが manual fulfillment を有効にする設定で、次のステップで変更します。
License Length: 発行した各キーが有効である期間、または No expiration。
Activations Limit: キーごとの activation の最大回数、または Unlimited。
Activation Message: 顧客がキーを activation したときに表示され、license key email に含まれる、任意の顧客向けメッセージ。

New License Key entitlement form with name, fulfillment mode, license length, activations limit, and activation message

Set Fulfillment Mode to Manual

Fulfillment Mode dropdown を開き、Automatic から Manual に変更します。以降のガイドはこの設定を前提としています。この設定がない場合、Dodo Payments はキーを自動的に生成してメールで送信し、保留中の grant は作成しません。Manual を選択すると、購入ごとに fulfillment が必要な Pending grant が作成されます。Create Entitlement をクリックして保存します。

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

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 です。省略した場合、または既存の entitlement を変更しない場合、その entitlement は automatic fulfillment のままです。manual に明示的に設定した entitlement だけが、保留中の grant を作成します。

Step 2 — Entitlement を Product に関連付ける

販売する product を開き、その Entitlements セクションに移動して、Step 1 で Manual に設定した License Key entitlement を選択します。1 つの product で、同じ購入においてこの license key を他の entitlement と一緒に提供できます。まだ product がない場合は、まず one-time product または subscription product を作成してください。checkout で販売する方法については、Integration Guideを参照してください。

Product entitlements panel with License Key selected — Selecting the License Key entitlement in the product entitlements panel.

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

Step 3 — 保留中の Grant を検出する

顧客が product を購入すると、Dodo Payments は キーが関連付けられていない Pending status の grant を作成し、entitlement_grant.created webhook を送信します。このイベントは、顧客がキーを待っていることを示すシグナルです。

Webhook をリッスンする

Dashboard の Developer → Webhooks で webhook endpoint を追加し、保留中の license-key grant に対して処理を実行します。Webhook は Standard Webhooks specification に従うため、standardwebhooks library で検証できます。

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_PAYMENTS_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'
  ) {
    // queueLicenseKeyFulfillment is your own job queue, not part of the SDK.
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

Grant payload には integration_type: "license_key" が含まれるため、追加の lookup なしで license-key grant を識別できます。Webhook delivery は繰り返される可能性があるため、すでに処理した webhook-id header のイベントはスキップしてください。完全な payload については、Entitlement Grant webhook referenceを参照してください。

List Grants API をポーリングする

Webhook に依存したくない場合は、License Key entitlement の grant を一覧表示し、status でフィルタリングします。License Key entitlement のすべての grant は license-key grant であるため、integration_type filter は必要ありません。

// Uses the client from Step 1.
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 -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  --data-urlencode "status=Pending"

Step 4 — キーを提供する

自社システムからキーの値を取得し、Fulfill License Key Grant endpoint に送信します。この call には Editor permission を持つ secret API key が必要です。これは public license endpoint の 1 つではありません。SDK でも利用でき、たとえば TypeScript では client.entitlements.grants.fulfillLicenseKey()、Python では client.entitlements.grants.fulfill_license_key() として公開されています。

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"
}

curl -X POST https://test.dodopayments.com/grants/entg_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'

Request Fields

string

必須

顧客に提供する license key string。最大 255 文字です。前後の whitespace は trim され、空の値または whitespace のみの値は拒否されます。

integer

キーごとの activation limit。1 以上である必要があります。省略した場合は、entitlement の Activations Limit が適用されます。

string

キーごとの expiry（ISO 8601）。省略した場合、one-time grant のキーは entitlement の License Length に従って expiry し、subscription grant のキーには expiry が設定されないため、その有効性は subscription に従います。

成功すると、grant は Delivered に移行し、Dodo Payments はキーを顧客にメールで送信します（automatic fulfillment の場合と同じ email です）。その後、license_key.created と entitlement_grant.delivered webhook event が発生します。メールには license key、product、activation limit、expiry、および activation instructions が含まれます。

Customer license key email showing the key, product, activation limit, expiry, and activation instructions — The license key email the customer receives once you fulfill the grant.

キーを自分でメール送信する必要はありません。grant が fulfillment されると、delivery は自動的に行われます。

Step 5 — エラーと Retry を処理する

endpoint は、delivery の前に grant を検証します。次の response を処理してください。

Status	Meaning	What to do
`200`	キーが提供されました。Grant は現在 `Delivered` です。	完了です。
`400`	License-key grant ではない、またはキーが空、もしくは whitespace のみです。	Request を修正してください。変更せずに retry しないでください。
`404`	その ID の grant が business に存在しません。	`grant_id` を確認してください。
`409`	Grant が fulfillment 待ちではありません（すでに delivery 済み、revoked、またはすでにキーがある）、またはキーの値がすでに存在します。	Grant がすでに delivery 済みの場合は、call を成功として扱います。キーが重複している場合は、別のキーを指定してください。
`422`	Request body の validation に失敗しました。たとえば `activations_limit` が 1 未満、またはキーが 255 文字を超えています。	Field を修正して retry してください。

Fulfillment は、timeout や 5xx response などの一時的なエラーに対して安全に retry できます。各 grant は 1 回だけ fulfillment できるため、成功したものの応答を受信できなかった call の後に retry すると、2 つ目のキーを発行したり重複した email を送信したりせず、409 が返されます。Grant の id を idempotency key として使用してください。

Flow を検証する

Flow を end to end でテストするには、次の手順を実行します。

test mode で product を購入します。checkout guidesを参照してください。
Webhook が status: "Pending" と integration_type: "license_key" を含む entitlement_grant.created を受信したこと、または status=Pending で filter した List Grants response に grant が表示されることを確認します。
test key を指定して fulfill endpoint を呼び出します。
Response に license_key が設定された status: "Delivered" が表示され、顧客がキーの email を受信し、entitlement_grant.delivered が発生することを確認します。

キーが提供されると、顧客は自動生成されたキーと同様に、public license endpoint に対してactivation と validationを実行できます。

Create Entitlement

fulfillment_mode: manual を使用して License Key entitlement を作成します。

List Grants

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

Fulfill License Key Grant

キーの値を提供し、grant を Delivered に移行します。

Entitlement Grant Webhooks

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

Integration Guides

Billing Deconstructions

Cookbooks

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

License Keys Overview

Fulfill License Key Grant API

仕組み

前提条件

Step 1 — Manual Mode で License Key Entitlement を作成する

Step 2 — Entitlement を Product に関連付ける

Step 3 — 保留中の Grant を検出する

Webhook をリッスンする

List Grants API をポーリングする

Step 4 — キーを提供する

Request Fields

Step 5 — エラーと Retry を処理する

Flow を検証する

関連する API Reference

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys Overview

Fulfill License Key Grant API

​仕組み

​前提条件

​Step 1 — Manual Mode で License Key Entitlement を作成する

​Step 2 — Entitlement を Product に関連付ける

​Step 3 — 保留中の Grant を検出する

​Webhook をリッスンする

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

​Step 4 — キーを提供する

​Request Fields

​Step 5 — エラーと Retry を処理する

​Flow を検証する

​関連する API Reference

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

仕組み

前提条件

Step 1 — Manual Mode で License Key Entitlement を作成する

Step 2 — Entitlement を Product に関連付ける

Step 3 — 保留中の Grant を検出する

Webhook をリッスンする

List Grants API をポーリングする

Step 4 — キーを提供する

Request Fields

Step 5 — エラーと Retry を処理する

Flow を検証する

関連する API Reference