License Keys

​

Cosa sono le chiavi di licenza?

• Licenze software: app desktop, plugin e CLI.
• Controlli per posto: limita le attivazioni per utente o dispositivo.
• Prodotti digitali: limita l’accesso a download, aggiornamenti o funzionalità premium.

​

Create a License Key Entitlement

1

Open Entitlements

Vai a Entitlements nella dashboard e fai clic su + per creare un entitlement.

2

Choose License Key

Seleziona License Keys, inserisci un Name e configura il comportamento di ogni chiave emessa:

• Fulfillment Mode: Automatic (impostazione predefinita) genera e invia tramite email ogni chiave. Manual consente di fornire personalmente ogni chiave. Consulta Manual Fulfillment.
• Activations Limit: il numero massimo di attivazioni attive per chiave, ad esempio 1 per un singolo utente o 5 per una licenza di team. Seleziona Unlimited per non applicare alcun limite.
• License Length: per quanto tempo una chiave rimane valida dopo l’emissione, ad esempio 30 giorni o 1 anno, oppure No expiration. Per i prodotti in abbonamento, scegli No expiration: le chiavi emesse per un abbonamento non scadono e la loro validità segue lo stato dell’abbonamento.
• Activation Message: istruzioni opzionali rivolte al cliente, fino a 2.500 caratteri, incluse nell’email che consegna la chiave. Ad esempio: Paste the key in Settings → License o Run: mycli activate <key>.

3

Save the Entitlement

Fai clic su Create Entitlement. Ora puoi collegare l’entitlement a qualsiasi prodotto.

​

Attach to Products

​

How Keys Are Issued

​

Comportamento della quantità

• Prodotti in abbonamento emettono una chiave per ogni posto (subscriptions.quantity).
• Prodotti una tantum emettono una chiave per ogni unità dell’articolo nella riga del carrello (product_cart.quantity).
• Concessioni API manuali emettono esattamente una chiave.

​

Modalità di evasione

• auto (predefinito, Automatic nella dashboard): Dodo Payments genera e invia tramite email la chiave al momento del pagamento o dell’abbonamento. Questo è il comportamento mostrato nella tabella precedente e si applica quando fulfillment_mode viene omesso.
• manual (Manual nella dashboard): ogni unità acquistata crea una concessione Pending senza chiave e devi fornire il valore di ogni chiave. Consulta Manual Fulfillment.

​

Evasione manuale

​

Quando usarla

• Usa le tue chiavi: la tua applicazione, un prodotto desktop o il tuo license server genera la chiave.
• Fornitori di terze parti: rivendi chiavi emesse da un fornitore a monte, come una chiave di gioco, una credenziale API o una licenza per una piattaforma partner.
• Inventario limitato: distribuisci codici da un insieme pre-allocato e li assegni uno alla volta.
• Revisione manuale: vuoi controllare un acquisto prima di concedere l’accesso.

​

Abilitare l’evasione manuale

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

​

Trovare le concessioni in attesa di evasione

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

​

Consegnare la chiave

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

​

Attivazione, convalida e disattivazione

​

Attivare una licenza

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

​

Convalidare una licenza

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

​

Disattivare un’istanza di attivazione

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

​

Gestire le chiavi

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

​

Importare chiavi di licenza esistenti tramite 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',
});

​

Differenze tra le chiavi in base all’origine

​

Chiavi di licenza nell’URL di ritorno

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

​

Gestione API

​

Webhook

​

Chiavi di licenza legacy

​

Best practice

• Scegli limiti di attivazione chiari: seleziona valori predefiniti come 1 per le app per singolo utente o 3–5 per le licenze di team e documentali per i tuoi clienti.
• Scrivi messaggi di attivazione precisi: i clienti li copiano dall’email della chiave di licenza, quindi percorsi e comandi esatti evitano richieste all’assistenza.
• Convalida le chiavi tramite API: per i prodotti connessi alla rete, chiama /licenses/validate invece di affidarti a un’attivazione memorizzata localmente.
• Usa i webhook per la revoca: gestisci entitlement_grant.revoked per disabilitare le funzionalità nell’app quando un cliente annulla o riceve un rimborso.
• Testa abbonamenti e acquisti una tantum: il comportamento delle chiavi di licenza differisce tra i due casi; ad esempio, le chiavi degli abbonamenti non scadono, quindi testali entrambi prima della pubblicazione.