Lizenzschlüssel

Generieren und liefern Sie einzigartige Lizenzschlüssel mit Aktivierungslimits und Ablauf. Lizenzschlüssel sind der Berechtigungstyp “License Key”. Sie werden bei Zahlung automatisch ausgegeben, sind an den Abonnementlebenszyklus gebunden und werden bei Kündigung oder Rückerstattung widerrufen.

Lizenzschlüssel sind der Berechtigungstyp “License Key”. Erstellen Sie eine License Key-Berechtigung einmalig mit dem gewünschten Aktivierungslimit, Ablauf und Anweisungen, verknüpfen Sie sie mit einem Produkt, und Dodo Payments generiert und liefert automatisch einen Schlüssel pro Kauf oder Abonnementplatz.

​

Was sind Lizenzschlüssel?

Lizenzschlüssel sind einzigartige Tokens, die den Zugriff auf Ihr Produkt autorisieren. Sie sind ideal für:

• Softwarelizenzierung: Desktop-Apps, Plugins und CLIs
• Pro-Benutzer-Kontrollen: Begrenzen Sie die Aktivierungen pro Benutzer oder Gerät
• Digitale Waren: Steuern Sie Downloads, Updates oder Premium-Funktionen

Innerhalb von Dodo Payments werden Lizenzschlüssel über das Berechtigungen System verwaltet, was bedeutet, dass der Lebenszyklus jedes Schlüssels (Erstellung, Ablauf, Widerruf, Neugewährung) von denselben Zahlungs- und Abonnementereignissen wie Ihre anderen Lieferungen gesteuert wird.

​

Erstellen Sie eine License Key-Berechtigung

1. Open Entitlements

   Gehen Sie zu Berechtigungen in Ihrem Dodo Payments-Dashboard und klicken Sie auf +, um eine neue Berechtigung zu erstellen.

2. Choose License Key

   Wählen Sie License Key als Integration. Konfigurieren Sie, wie sich jeder ausgegebene Schlüssel verhält:

   • Aktivierungslimit: Maximale gleichzeitige Aktivierungen pro Schlüssel (z.B. 1 für Einzelbenutzer, 5 für Teamlizenzen, leer lassen für unbegrenzt).
   • Dauer: Wie lange der Schlüssel nach der Ausgabe gültig bleibt (z.B. 30 Tage, 1 Jahr). Für Abonnement-gestützte Schlüssel leer lassen; Schlüssel bleiben gültig, solange das Abonnement aktiv ist.
   • Aktivierungsanweisungen: Kundengerichtete Anweisungen, die mit dem Schlüssel per E-Mail gesendet werden. Beispiele: Paste the key in Settings → License oder Run: mycli activate <key>.

   
3. Save the entitlement

   Speichern. Die Berechtigung ist jetzt verfügbar, um sie mit jedem Produkt zu verknüpfen.

​

An Produke anhängen

Öffnen Sie ein Produkt, erweitern Sie Erweiterte Einstellungen → Berechtigungen & Gutschriften und wählen Sie Ihre License Key-Berechtigung aus. Ein einzelnes Produkt kann gemeinsam mit anderen Berechtigungen (Discord-Zugang, Dateidownloads, GitHub-Repo-Zugang usw.) einen Lizenzschlüssel bei demselben Kauf liefern.

---

​

Wie Schlüssel ausgegeben werden

Die Schlüsselausgabe folgt dem Standard Zuwendungslebenszyklus:

Ereignis	Verhalten
payment.succeeded (einmalig)	Generieren Sie einen Schlüssel pro quantity gekauft. Der Ablauf des Schlüssels berücksichtigt die Dauer der Berechtigung.
subscription.active	Generieren Sie einen Schlüssel pro Abonnement quantity (Sitz). Der Schlüssel hat kein Ablaufdatum; die Gültigkeit ist an den Abonnementstatus gebunden.
subscription.renewed	No-op. Vorhandene Schlüssel bleiben bestehen.
subscription.on_hold	Deaktivieren Sie die Schlüssel. Sie werden reaktiviert, wenn das Abonnement von der Haltestellung genommen wird.
subscription.cancelled / expired	Deaktivieren Sie die Schlüssel dauerhaft.
subscription.plan_changed	Deaktivieren Sie die alten Schlüssel; geben Sie neue für den neuen Plan aus.
refund.succeeded (einmalig)	Deaktivieren Sie die Schlüssel.
Manuelles Widerrufen über API/Dashboard	Deaktivieren Sie die Schlüssel mit revocation_reason: manual. Diese werden bei Abonnementverlängerung nicht automatisch erneut vergeben.
Lizenzschlüssel direkt deaktiviert	Widerrufen Sie die Zuwendung mit revocation_reason: license_key_disabled. Das erneute Aktivieren des Schlüssels reaktiviert die Zuwendung automatisch.

​

Verhaltensweise der Menge

• Abonnementprodukte geben einen Schlüssel pro Sitzplatz aus (subscriptions.quantity).
• Einmalprodukte geben einen Schlüssel pro Warenkorbposition aus (product_cart.quantity).
• Manuelle API-Zuwendungen geben genau einen Schlüssel aus.

​

Erfüllungsmodus

Jede Lizenzschlüsselberechtigung hat einen fulfillment_mode, der steuert, wer den Schlüssel bereitstellt:

• auto (Standard): Dodo Payments generiert und sendet den Schlüssel automatisch per E-Mail bei Zahlung oder Abonnement. Dieses Verhalten wird oben beschrieben und gilt, wenn fulfillment_mode weggelassen wird.
• manual: Der Kauf erstellt eine pending-Berechtigung ohne Schlüssel, und Sie liefern jeden Schlüsselwert selbst. Siehe Manuelle Erfüllung unten.

---

​

Manuelle Erfüllung

Standardmäßig generiert und sendet Dodo Payments einen Lizenzschlüssel per E-Mail, sobald ein Kunde zahlt. Bei der manuellen Erfüllung liefern Sie den Schlüssel selbst: Der Kauf erstellt eine pending-Berechtigung ohne Schlüssel, benachrichtigt Sie und wartet darauf, dass Sie den Schlüsselwert einreichen. Verwenden Sie es, wenn Schlüssel aus Ihrem eigenen System, einem Drittanbieter oder einem begrenzten Pool vorab gedruckter Codes stammen.

Sie suchen nach einem Schritt-für-Schritt-Aufbau? Lesen Sie den Manual License Key Fulfillment Integration Guide für eine vollständige Anleitung von der Produkterstellung bis zur Lieferung des Schlüssels.

​

Wann es zu verwenden ist

Die automatische Erfüllung ist die richtige Standardeinstellung für die meisten Softwarelizenzen. Wählen Sie die manuelle Erfüllung, wenn Dodo Payments den Schlüssel nicht selbst erstellen kann:

• Bring-your-own-keys: Der Schlüssel wird von Ihrer Anwendung, einem Desktop-Produkt oder Ihrem eigenen Lizenzserver generiert.
• Drittanbieter: Sie verkaufen Schlüssel eines externen Anbieters weiter (ein Spielschlüssel, eine API-Zugangsdaten, eine Partnerplattform).
• Begrenzter Bestand: Sie geben Codes aus einem vorab zugewiesenen Pool aus und möchten sie einzeln zuweisen.
• Manuelle Überprüfung: Sie möchten einen Kauf überprüfen, bevor Sie Zugriff gewähren.

​

Manuelle Erfüllung aktivieren

Setzen Sie fulfillment_mode: "manual" in der Integrationskonfiguration der Lizenzschlüsselberechtigung:

Node.js

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

fulfillment_mode ist rückwärtskompatibel. Berechtigungen, die vor dieser Einstellung erstellt wurden, haben keinen fulfillment_mode und verhalten sich weiterhin als auto. Der Wechsel zu manual betrifft nur Berechtigungen, die nach der Änderung erstellt wurden; bereits gelieferte Schlüssel bleiben unberührt.

​

Berechtigungen finden, die auf Erfüllung warten

Wenn ein Kunde ein Produkt im manuellen Modus kauft, wird die Berechtigung im pending-Status ohne Schlüssel erstellt und ein entitlement_grant.created Webhook wird mit integration_type: "license_key" und status: "pending" ausgelöst. Sie können auf diesen Webhook reagieren oder den Endpunkt List Grants mit den Filtern integration_type und status abfragen:

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

​

Den Schlüssel liefern

Reichen Sie den Schlüssel mit dem Endpunkt Fulfill License Key Grant ein. Die Berechtigung wechselt zu delivered und der Kunde erhält den Schlüssel automatisch — die gleiche E-Mail, die er auch bei automatischer Erfüllung erhalten würde.

cURL

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

activations_limit und expires_at sind optional und greifen auf die Berechtigungskonfiguration zurück, wenn sie weggelassen werden. Jede Berechtigung kann einmal erfüllt werden; das erneute Versuchen einer bereits erfüllten Berechtigung gibt 409 zurück, anstatt einen zweiten Schlüssel auszugeben.

Sie müssen den Schlüssel nicht selbst per E-Mail versenden — die Lieferung erfolgt automatisch, wenn die Berechtigung erfüllt wird. Dies unterscheidet sich von Schlüssel importieren über POST /license_keys, was bewusst nicht den Kunden benachrichtigt.

---

​

Aktivierung, Validierung, Deaktivierung

Die Aktivierungs-, Validierungs- und Deaktivierungs-API-Endpunkte sind öffentlich und erfordern keinen API-Schlüssel. Verwenden Sie sie direkt von Desktop-Software, CLIs oder browserbasierten Clients, um Schlüssel zur Laufzeit zu verifizieren.

Öffentliche Endpunkte: Die Endpunkte zur Aktivierung, Deaktivierung und Validierung von Lizenzen sind öffentlich und erfordern keinen API-Schlüssel. Rufen Sie sie direkt von Ihren Client-Anwendungen auf, ohne Ihre API-Zugangsdaten offenzulegen.

​

Eine Lizenz aktivieren

TypeScript

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

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

console.log(response.id);

​

Eine Lizenz validieren

TypeScript

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

console.log(response.valid);

​

Eine Aktivierungsinstanz deaktivieren

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

---

​

Schlüssel verwalten

Öffnen Sie die Lizenzschlüsselberechtigung in Ihrem Dashboard, um jede Berechtigung zu sehen (eine Zeile pro Kunden-Schlüssel) mit Lieferdatum, Aktivierungsanzahl und einer Rücknahmeaktion. Jedes Berechtigungsdetail zeigt den zugehörigen Lizenzschlüssel, das Ablaufdatum, die verwendeten Aktivierungen und das Aktivierungslimit an.

Sie können Berechtigungen auch programmatisch auflisten:

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

​

Bestehende Lizenzschlüssel über die API importieren

Haben Sie bereits Lizenzschlüssel in einem anderen System? Verwenden Sie die Create License Key API, um sie in Dodo Payments zu importieren. So können Sie bestehende Schlüssel migrieren, ohne Ihre Kunden zu stören – sie können weiterhin gegen die gleichen Schlüsselstränge aktivieren, validieren und deaktivieren, ohne dass sie erneut ausgegeben werden.

Lizenzschlüssel, die über die API erstellt oder aktualisiert werden, lösen keine E-Mail-Benachrichtigungen an Kunden aus. Wenn Sie Kunden über einen importierten Schlüssel informieren müssen, behandeln Sie dies separat in Ihrer Anwendung.

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

​

Wie sich Schlüssel je nach Quelle unterscheiden

Feld	Automatisch generierter Schlüssel	Manuell erfüllter Schlüssel	Importierter Schlüssel
source	"auto"	"manual"	"import"
Herkunft	Generiert von Dodo Payments bei Zahlung	Von Ihnen bereitgestellt gegen eine ausstehende Berechtigung	Erstellt/migriert über POST /license_keys
payment_id	Auf die ursprüngliche Zahlung gesetzt	Von der Berechtigung oder ihrem Abonnement gelöst	null (keine Dodo Payments-Transaktion)
subscription_id	Festgelegt, wenn über ein Abonnement ausgegeben	Festgelegt, wenn die Berechtigung aus einem Abonnement stammt	null, es sei denn, explizit verknüpft
E-Mail-Benachrichtigung des Kunden	Bei Ausgabe gesendet	Bei Erfüllung gesendet	Nicht gesendet – separat behandeln

Verwenden Sie das Feld source in GET /license_keys-Antworten, um migrierten Bestand und manuell erfüllte Schlüssel von organisch ausgegebenen Schlüsseln zu unterscheiden, wenn Sie eine Abstimmung oder Prüfung durchführen.

Migration von Polar.sh oder Lemon Squeezy? Die dodo-migrate CLI automatisiert den Massenimport von Produkten, Kunden, Rabatten und Lizenzschlüsseln in einem einzigen Befehl und ordnet externe IDs automatisch Dodo-IDs zu.

---

​

Lizenzschlüssel in der Rückgabe-URL

Wenn ein Kunde einen Kauf für ein Produkt mit einer Lizenzschlüsselberechtigung abschließt, wird der generierte Schlüssel automatisch als Abfrageparameter an Ihre return_url angehängt. Auf diese Weise können Sie den Schlüssel sofort auf Ihrer Erfolgseite anzeigen, ohne einen zusätzlichen API-Aufruf machen zu müssen.

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

Wenn der Kauf mehrere Schlüssel generiert (Menge > 1), werden diese durch Kommas getrennt:

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

Für Abonnements wird subscription_id anstelle von payment_id verwendet:

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

Analysieren Sie den license_key-Parameter auf Ihrer Rückgabeseite, um den Schlüssel sofort anzuzeigen und die Erfahrung nach dem Kauf zu verbessern.

---

​

API-Management

Lifecycle Operations (Public Endpoints)

Aktivierung, Deaktivierung und Validierung sind öffentlich; kein API-Schlüssel erforderlich.

Activate License

Erstellen oder aufzeichnen einer Aktivierungsinstanz für einen Lizenzschlüssel.

Deactivate License

Eine vorherige Aktivierung widerrufen, um Kapazität freizugeben.

Validate License

Überprüfen Sie die Authentizität, den Status und die Einschränkungen, bevor Sie Zugriff gewähren.

License Key Management

Erstellen, auflisten, abrufen und aktualisieren von einzelnen Lizenzschlüssel-Datensätzen. Verwenden Sie diese, um vorhandene Schlüssel zu importieren oder Nutzungsdetails abzurufen.

Create License Key

Einen neuen Lizenzschlüssel erstellen oder einen bestehenden importieren.

List License Keys

Alle Schlüssel mit Status und Nutzungsdetails durchsuchen.

Get License Key

Einen spezifischen Schlüssel und seine Metadaten abrufen.

Update License Key

Ablauf, Aktivierungslimits oder Aktivierung/Deaktivierung eines Schlüssels ändern.

Entitlement Management

Verwalten der Lizenzschlüsselberechtigung selbst: ihr Aktivierungslimit, ihre Dauer und ihre Anweisungen.

Create Entitlement

Eine Lizenzschlüsselberechtigung erstellen.

Update Entitlement

Die Konfiguration der Berechtigung aktualisieren.

List Grants

Die für eine Berechtigung ausgestellten Schlüssel auflisten.

Revoke Grant

Einen Kundenschlüssel manuell widerrufen.

---

​

Webhooks

Die Übergabe und der Widerruf von Lizenzschlüsseln lösen die vier entitlement_grant.* Webhook-Ereignisse aus. Die Berechtigungspayload enthält ein ausgefülltes license_key-Objekt mit dem Schlüssel, dem Ablaufdatum, den verwendeten Aktivierungen und dem Limit.

Die Legacy license_key.*-Ereignisse (license_key.created) werden weiterhin für den Lebenszyklus des zugrunde liegenden Lizenzschlüssel-Datensatzes ausgelöst; siehe die License Key webhook payload page.

Für neue Integrationen hören Sie auf entitlement_grant.delivered anstelle von license_key.created. Das Berechtigungsereignis zeigt an, dass die Lieferung für alle Integration auf dem Produkt abgeschlossen ist, nicht nur für den Lizenzschlüssel.

---

​

Legacy-Lizenzschlüssel

Produkte, die mit dem älteren license_key_enabled-Flag erstellt wurden, wurden automatisch migriert zu einer Lizenzschlüsselberechtigung. Die Migration ist transparent: Die Schlüssel bestehender Kunden funktionieren weiterhin unverändert, die öffentlichen /licenses/activate, /licenses/validate, /licenses/deactivate-Endpunkte funktionieren weiterhin, und die /license_keys/*-API-Endpunkte lesen und schreiben weiterhin in den gleichen Schlüsselspeicher.

Der eigenständige Lizenzschlüssel-Dashboard-Abschnitt bleibt als flache Liste aller ausgegebenen Schlüssel verfügbar, nützlich für Audits und Suchvorgänge. Neue Konfigurationen (Änderung von Aktivierungslimits, -dauern oder -anweisungen) sollten durch Bearbeiten der migrierten Lizenzschlüsselberechtigung unter Berechtigungen vorgenommen werden.

---

​

Best Practices

• Halten Sie die Aktivierungslimits klar: Wählen Sie sinnvolle Standardeinstellungen (1 für Einzelbenutzeranwendungen, 3–5 für Teamlizenzen) und dokumentieren Sie diese.
• Bieten Sie präzise Aktivierungsanweisungen: Kunden kopieren diese aus ihrer E-Mail, so dass genaue Pfade und Befehle Support-Tickets einsparen.
• Validieren Sie Schlüssel serverseitig: Für netzwerkverbundene Produkte validieren Sie über /licenses/validate anstelle von lokalem Caching der Aktivierung.
• Verwenden Sie Webhooks für den Widerruf: Hören Sie auf entitlement_grant.revoked, um In-App-Funktionen sofort zu deaktivieren, wenn ein Kunde kündigt oder erstattet.
• Testen Sie mit Abonnements und Einmalzahlungen: Das Verhalten von Lizenzschlüsseln unterscheidet sich subtil zwischen den beiden, testen Sie daher beide, bevor Sie live gehen.