Manual License Key Fulfillment Integration Guide

• 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.

​

How It Works

​

Prerequisites

• Dodo Payments merchant account।
• एक API key, जिसे Developer → API Keys के अंतर्गत बनाया गया हो और DODO_PAYMENTS_API_KEY में stored हो, तथा Developer → Webhooks से webhook signing secret, जो DODO_PAYMENTS_WEBHOOK_KEY में stored हो। API key generation guide देखें।
• ऐसा backend endpoint जो webhooks receive कर सके।

​

Step 1 — Manual Mode में License Key Entitlement बनाएँ

• Dashboard
• API

1

Open Entitlements

Dashboard में Entitlements पर जाएँ और entitlement बनाने के लिए + पर click करें।

2

Choose License Key

License Keys select करें और Name दर्ज करें। Form में ये fields हैं:

• Fulfillment Mode: default रूप से Automatic। यही वह setting है जो manual fulfillment enable करती है और जिसे आप अगले step में बदलेंगे।
• License Length: प्रत्येक issued key कितने समय तक valid रहती है, या No expiration।
• Activations Limit: प्रत्येक key के लिए activations की maximum संख्या, या Unlimited।
• Activation Message: customer-facing optional message, जो customer के key activate करने पर दिखता है और license key email में शामिल होता है।

3

Set Fulfillment Mode to Manual

Fulfillment Mode dropdown खोलें और इसे Automatic से Manual में बदलें। इस guide का बाकी हिस्सा इसी setting पर निर्भर करता है: इसके बिना Dodo Payments keys automatically generate और email करता है तथा कोई pending grant नहीं बनाता। Manual select करने पर प्रत्येक purchase आपके द्वारा fulfill किए जाने वाला एक Pending grant बनाता है। Save करने के लिए Create Entitlement पर click करें।

integration_config.fulfillment_mode को manual पर set करके entitlement बनाएँ।

Node.js

Python

cURL

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_...

See all 19 lines

​

Step 2 — Entitlement को Product से Attach करें

​

Step 3 — Pending Grants का पता लगाएँ

​

Webhook को Listen करें

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

​

या List Grants API को Poll करें

// 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 — Key Deliver करें

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

​

Step 5 — Errors और Retries को Handle करें

​

Flow Verify करें

1. Test mode में product खरीदें। checkout guides देखें।
2. Confirm करें कि आपके webhook को entitlement_grant.created मिला है, जिसमें status: "Pending" और integration_type: "license_key" हैं, या grant status=Pending से filtered List Grants response में दिखाई देता है।
3. Test key के साथ fulfill endpoint को call करें।
4. Confirm करें कि response में populated license_key के साथ status: "Delivered" दिखता है, customer को key email मिलती है और entitlement_grant.delivered fire होता है।

​

Related API Reference