Manual License Key Fulfillment Integration Guide

Hướng dẫn này trình bày từng bước xây dựng hệ thống cấp phát license key thủ công từ đầu đến cuối. Thay vì để Dodo Payments tự động tạo key sau khi thanh toán, mỗi giao dịch mua sẽ tạo một grant Pending và chờ bạn cung cấp giá trị key từ hệ thống riêng, nhà cung cấp bên thứ ba hoặc một pool mã hữu hạn. By the end you will have:

A product with a License Key entitlement set to manual fulfillment.
A webhook listener that detects when a customer is waiting for a key.
A fulfillment call that delivers the key and notifies the customer automatically.

License Keys overview

The full license key lifecycle and the fulfillment_mode setting.

Fulfill License Key Grant API

API reference for the endpoint you call to deliver a key.

How It Works

Manual fulfillment changes only the issuance step. Activation, validation, deactivation, expiry, and revocation behave exactly like an auto-generated key once delivered.

Prerequisites

To follow this guide you’ll need:

A Dodo Payments merchant account.
Your API key (DODO_PAYMENTS_API_KEY) and webhook secret key from the dashboard. See the API key generation guide.
A backend endpoint that can receive webhooks.

Use https://test.dodopayments.com and test-mode credentials while building. Switch to https://live.dodopayments.com and live keys when you go to production.

Step 1 — Create a License Key Entitlement in Manual Mode

An entitlement is a reusable definition of what you deliver. Create a License Key entitlement and set its fulfillment_mode to manual.

Dashboard
API

Open Entitlements

Go to Entitlements in your dashboard and click + to create a new entitlement.

Choose License Key

Select License Key as the integration and give it a Name. The form exposes these fields:

Fulfillment Mode — Automatic by default. This is the setting that enables manual fulfillment; you change it in the next step.
License Length — how long each issued key stays valid, or No expiration.
Activations Limit — maximum activations per key, or Unlimited.
Activation Message — optional customer-facing message shown when they activate the key.

Biểu mẫu entitlement New License Key với tên, chế độ cấp phát, thời hạn license, giới hạn số lần kích hoạt và thông báo kích hoạt

Set Fulfillment Mode to Manual

Mở menu thả xuống Fulfillment Mode và chuyển từ Automatic sang Manual. Đây là cài đặt chi phối toàn bộ hướng dẫn này — nếu không bật, key sẽ được tự động tạo và gửi qua email, đồng thời không có grant đang chờ nào được tạo. Khi chọn Manual, mỗi giao dịch mua sẽ tạo một grant Pending để bạn cấp phát. Nhấp vào Create Entitlement để lưu.

Create the entitlement with integration_config.fulfillment_mode set to 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 defaults to auto. Omitting it, or leaving an existing entitlement unchanged, keeps the automatic behavior. Only entitlements explicitly set to manual create pending grants.

Step 2 — Attach the Entitlement to a Product

Open the product you want to sell, expand Advanced Settings → Entitlements & Credits, and select the License Key entitlement you set to Manual in Step 1. A single product can deliver this license key alongside other entitlements on the same purchase.

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

Chế độ cấp phát là thuộc tính của entitlement, không phải của product. Vì bạn đã đặt chế độ này thành Manual ở Bước 1, mọi product được liên kết với entitlement này sẽ tạo grant license key Pending khi mua — bạn không cần cấu hình thêm gì ở đây.

If you don’t have a product yet, create one first (one-time or subscription). See the One-time Payments Integration Guide for selling the product through checkout.

Step 3 — Detect Pending Grants

Khi customer mua product, Dodo Payments sẽ tạo một grant ở trạng thái Pending, chưa gắn key, và gửi một webhook entitlement_grant.created. Đây là tín hiệu cho biết có customer đang chờ key.

Listen for the webhook

Set up a webhook endpoint (Developer → Webhooks in the dashboard) and act on pending license-key grants. The implementation follows the Standard Webhooks specification.

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');
}

The grant payload carries integration_type: "license_key", so you can recognize a license-key grant without an extra lookup. See the Entitlement Grant webhook reference for the full payload.

Or poll the List Grants API

Nếu bạn không muốn dựa vào webhooks, hãy liệt kê các quyền cấp cho License Key của bạn và lọc theo status. Mọi quyền cấp trên License Key đều là quyền cấp license-key, vì vậy không cần lọc integration_type:

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 — Deliver the Key

Obtain the key value from your own system, then submit it with the Fulfill License Key Grant endpoint. This requires your secret API key (Editor permission); it is not one of the public license endpoints.

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/grant_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

bắt buộc

The license key string to deliver to the customer. Whitespace is trimmed; an empty or whitespace-only value is rejected.

integer

Per-key activation limit. Falls back to the entitlement config when omitted.

string

Per-key expiry (ISO 8601). Falls back to the entitlement config’s duration when omitted. For subscription-issued grants, validity remains tied to the subscription regardless.

Khi thành công, grant chuyển sang Delivered, customer sẽ tự động nhận key (qua email giống như khi sử dụng chế độ cấp phát tự động), đồng thời các sự kiện webhook license_key.created và entitlement_grant.delivered sẽ được gửi. The customer receives an email with the license key, the product, activation limit, expiry, and your 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.

You do not need to email the key yourself — delivery happens automatically when the grant is fulfilled.

Step 5 — Handle Errors and Retries

The endpoint validates the grant before delivering anything. Handle these responses:

Trạng thái	Ý nghĩa	Việc cần làm
`200`	Key đã được gửi, grant hiện ở trạng thái `Delivered`.	Hoàn tất.
`400`	Không phải grant license key, hoặc key trống/chỉ chứa khoảng trắng.	Sửa request; không retry nguyên trạng.
`404`	Không có grant với ID đó cho business của bạn.	Xác minh `grant_id`.
`409`	Grant không chờ cấp phát (đã được gửi hoặc đã có key), hoặc giá trị key đã tồn tại.	Nếu đã được gửi, hãy xem như thành công. Nếu key bị trùng, hãy cung cấp key khác.
`422`	Request body không vượt qua bước validation (ví dụ: `activations_limit < 1`).	Sửa field và retry.

Fulfillment is safe to retry on transient errors (timeouts, 5xx). Each grant can be fulfilled only once, so a retry after a successful-but-unacknowledged call returns 409 rather than issuing a second key or sending a duplicate email. Use the grant id as your idempotency key.

Verify the Flow

Mua product ở test mode (xem hướng dẫn checkout).
Xác nhận webhook của bạn đã nhận entitlement_grant.created với status: "Pending" và integration_type: "license_key", hoặc grant xuất hiện trong response của List Grants với các bộ lọc đó.
Gọi endpoint fulfill với một key kiểm thử.
Xác nhận response hiển thị status: "Delivered" cùng với license_key đã được điền, customer nhận được email chứa key và entitlement_grant.delivered được gửi.

Once delivered, the customer can activate and validate the key against the public license endpoints exactly like an auto-generated key.

Create Entitlement

Tạo entitlement License Key với fulfillment_mode: manual.

List Grants

Lọc theo status và customer_id để tìm các grant đang chờ.

Fulfill License Key Grant

Cung cấp giá trị key và chuyển grant sang trạng thái đã gửi.

Entitlement Grant Webhooks

Các sự kiện entitlement_grant.* báo hiệu grant đang chờ và đã được gửi.

Integration Guides

Billing Deconstructions

Cookbooks

Manual License Key Fulfillment Integration Guide

License Keys overview

Fulfill License Key Grant API

How It Works

Prerequisites

Step 1 — Create a License Key Entitlement in Manual Mode

Step 2 — Attach the Entitlement to a Product

Step 3 — Detect Pending Grants

Listen for the webhook

Or poll the List Grants API

Step 4 — Deliver the Key

Request fields

Step 5 — Handle Errors and Retries

Verify the Flow

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys overview

Fulfill License Key Grant API

​How It Works

​Prerequisites

​Step 1 — Create a License Key Entitlement in Manual Mode

​Step 2 — Attach the Entitlement to a Product

​Step 3 — Detect Pending Grants

​Listen for the webhook

​Or poll the List Grants API

​Step 4 — Deliver the Key

​Request fields

​Step 5 — Handle Errors and Retries

​Verify the Flow

​Related API Reference

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

How It Works

Prerequisites

Step 1 — Create a License Key Entitlement in Manual Mode

Step 2 — Attach the Entitlement to a Product

Step 3 — Detect Pending Grants

Listen for the webhook

Or poll the List Grants API

Step 4 — Deliver the Key

Request fields

Step 5 — Handle Errors and Retries

Verify the Flow

Related API Reference