License Keys

​

What Are License Keys?

• Software licensing: desktop apps, plugins, and CLIs.
• Per-seat controls: limit activations per user or device.
• Digital goods: gate downloads, updates, or premium features.

​

Create a License Key Entitlement

1

Open Entitlements

Go to Entitlements in the dashboard and click + to create an entitlement.

2

Choose License Key

Select License Keys, enter a Name, and configure how each issued key behaves:

• Fulfillment Mode: Automatic (the default) generates and emails each key. Manual lets you supply each key yourself. See Manual Fulfillment.
• Activations Limit: the maximum number of active activations per key, for example 1 for a single user or 5 for a team license. Select Unlimited for no limit.
• License Length: how long a key stays valid after it’s issued, for example 30 days or 1 year, or No expiration. For subscription products, choose No expiration: keys issued for a subscription have no expiry, and their validity follows the subscription status.
• Activation Message: optional customer-facing instructions, up to 2,500 characters, included in the email that delivers the key. For example: Paste the key in Settings → License or Run: mycli activate <key>.

3

Save the Entitlement

Click Create Entitlement. You can now attach the entitlement to any product.

​

Attach to Products

​

How Keys Are Issued

​

Quantity Behavior

• Subscription products issue one key per seat (subscriptions.quantity).
• One-time products issue one key per unit of the cart line item (product_cart.quantity).
• Manual API grants issue exactly one key.

​

Fulfillment Mode

• auto (default, Automatic in the dashboard): Dodo Payments generates and emails the key on payment or subscription. This is the behavior in the table above, and it applies when fulfillment_mode is omitted.
• manual (Manual in the dashboard): each unit purchased creates a Pending grant with no key, and you supply each key value. See Manual Fulfillment.

​

Manual Fulfillment

​

When to Use It

• Bring your own keys: your application, a desktop product, or your own license server generates the key.
• Third-party vendors: you resell keys that an upstream provider issues, such as a game key, an API credential, or a partner platform license.
• Finite inventory: you hand out codes from a pre-allocated pool and assign them one at a time.
• Human review: you want to check a purchase before you release access.

​

Enable Manual Fulfillment

// `client` is a DodoPayments instance created with your API key.
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',
  },
});

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

​

Find Grants Awaiting Fulfillment

const pending = await client.customers.listEntitlementGrants('cus_abc123', {
  integration_type: 'license_key',
  status: 'Pending',
});

​

Deliver the Key

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

​

Activation, Validation, Deactivation

​

Activate a License

import DodoPayments from 'dodopayments';

// The license endpoints don't check the token, but the SDK requires a value.
// Never ship your secret API key in client software.
const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' });

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

from dodopayments import DodoPayments

# The license endpoints don't check the token, but the SDK requires a value.
client = DodoPayments(bearer_token="public", environment="test_mode")

response = client.licenses.activate(
    license_key="PRO-AAAA-BBBB-CCCC-DDDD",
    name="Device Name",
)
print(response.id)

curl -X POST https://test.dodopayments.com/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "name": "Device Name"
  }'

​

Validate a License

// Uses the client from the activation example.
const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

curl -X POST https://test.dodopayments.com/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'

​

Deactivate an Activation Instance

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'lki_abc123',
});

​

Manage Keys

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

for (const grant of grants.items) {
  console.log(grant.license_key?.key, grant.license_key?.activations_used);
}

​

Import Existing License Keys via API

const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​

How Keys Differ by Source

​

License Keys in Return URL

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001%2CLK-002&email=customer%40example.com

https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com

​

API Management

​

Webhooks

​

Legacy License Keys

​

Best Practices

• Choose clear activation limits: pick defaults such as 1 for single-user apps or 3–5 for team licenses, and document them for your customers.
• Write precise activation messages: customers copy them from the license key email, so exact paths and commands prevent support tickets.
• Validate keys against the API: for network-connected products, call /licenses/validate instead of relying on a locally cached activation.
• Use webhooks for revocation: handle entitlement_grant.revoked to disable in-app features when a customer cancels or receives a refund.
• Test subscriptions and one-time purchases: license key behavior differs between the two, for example subscription keys don’t expire, so test both before you go live.