Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Le entitlements trasformano un pagamento riuscito o un abbonamento attivo in accesso reale: una chiave di licenza nella casella email del tuo cliente, un ruolo Discord, un repository GitHub, un template Notion, un link remix Framer, un invito a chat Telegram, o un pacchetto di file scaricabili. Dodo Payments emette, traccia e revoca automaticamente tale accesso man mano che il ciclo di vita del pagamento cambia.
Dashboard delle entitlements con un elenco di entitlements a sinistra e l'attività di concessione a destra

​
Cosa sono le Entitlements?

Un’entitlement è una definizione riutilizzabile di qualcosa che fornisci a un cliente: una chiave di licenza Pro, un ruolo “Patrons” su Discord, accesso al tuo repository GitHub privato, un pacchetto di e-book scaricabile. Le entitlements si associano ai prodotti, e Dodo Payments si occupa del resto. Quando un cliente acquista il prodotto, Dodo Payments crea una grant, un’emissione singola di quella entitlement al cliente. Le grants passano attraverso una piccola serie di stati: pending mentre la consegna è in corso, delivered una volta che il cliente ha accesso, failed se la consegna non è stata completata, e revoked quando l’accesso viene ritirato.
Le entitlements controllano il fulfillment (il cliente ha accesso?). I crediti controllano il consumo (quanto possono utilizzare?). Entrambi possono essere collegati allo stesso prodotto. Vedi Credit-Based Billing per i crediti.

​
Integrazioni Disponibili

Dodo Payments consegna ogni entitlement attraverso un’integrazione dedicata. Scegli l’integrazione che corrisponde a ciò che vendi.

License Keys

Genera chiavi di licenza uniche con limiti di attivazione e scadenza. Ideale per software, plugin e CLI.

Digital Files

Fornisci file scaricabili (e-book, template, media) con URL di download presigned e istruzioni opzionali.

Discord

Concedi a un cliente un ruolo nel tuo server Discord quando acquista. Revoca automaticamente alla cancellazione.

GitHub

Aggiungi i clienti come collaboratori a un repository privato al livello di autorizzazione che scegli.

Telegram

Aggiungi i clienti a una chat o canale Telegram privato dopo l’acquisto.

Framer

Sblocca un link remix per template Framer per i clienti paganti.

Notion

Duplica un template Notion nello spazio di lavoro del cliente all’acquisto.

​
Come Funzionano le Grants

Le grants sono guidate dagli stessi eventi di pagamento e abbonamento che ricevi già come webhook. Non è necessario chiamare l’API delle grants per gli acquisti. Dodo Payments crea e revoca le grants automaticamente in base al ciclo di vita del pagamento sottostante.

​
Ciclo di vita della Grant

1

Created

Una grant è creata quando un pagamento viene completato o un abbonamento diventa attivo. Le chiavi di licenza passano direttamente a delivered. Tutte le altre integrazioni iniziano in pending. Le integrazioni basate su OAuth (Discord, GitHub, Notion) includono un oauth_url che il cliente deve visitare per completare il consenso. Le integrazioni dirette alla piattaforma (Telegram, Framer, File Digitali) restano in pending brevemente mentre la consegna viene fornita, poi passano a delivered.
2

Delivered

Una volta completata la consegna (chiave di licenza generata, ruolo assegnato, accesso al repository concesso, link ai file risolti, OAuth completato), la grant passa a delivered e delivered_at è impostato.
3

Failed

Se la chiamata all’integrazione restituisce un errore non ripetibile (token OAuth revocato, permesso negato, file non più esistente), la grant passa a failed. I campi error_code e error_message catturano il motivo.
4

Revoked

Quando l’accesso viene ritirato (abbonamento cancellato, rimborso emesso, o revoca iniziata dal commerciante), la grant passa a revoked. Il campo revocation_reason registra il trigger.

​
Comportamento delle Grants per Evento

EventoComportamento
payment.succeeded (pagamento una tantum)Emissione di una grant per ogni entitlement collegata.
payment.succeeded (pagamento collegato all’abbonamento)Nessuna operazione. Le grants sono guidate dall’evento di abbonamento di seguito.
subscription.activeEmetti grants per qualsiasi entitlement collegata che non abbia già una. Riconcedi tutte le grants precedentemente revocate per lo stesso abbonamento.
subscription.renewedNessuna operazione. Le grants esistenti persistono oltre i rinnovi.
subscription.on_holdRevoca tutte le grants consegnate e in sospeso. revocation_reason: subscription_on_hold.
subscription.cancelledRevoca tutto. revocation_reason: subscription_cancelled.
subscription.expiredRevoca tutto. revocation_reason: subscription_expired.
subscription.plan_changedRevoca tutte le grants attuali, poi emetti grants per le entitlements del nuovo piano. revocation_reason: plan_changed.
refund.succeeded (pagamento una tantum)Revoca grants per quel pagamento. revocation_reason: refund.
Revoca manuale APIRevoca con revocation_reason: manual. Le revoche manuali non sono ripetute automaticamente al rinnovo dell’abbonamento.
Chiave di licenza disabilitataPer grants con chiave di licenza, disabilitare la chiave sottostante revoca la grant con revocation_reason: license_key_disabled. La grant è riattivata automaticamente se la chiave viene riabilitata.
Drift della piattaforma rilevatoSe il lato piattaforma di un’integrazione si disallinea (un ruolo Discord rimosso manualmente, l’App GitHub che perde accesso al repository, o un passaggio di riconciliazione che rileva un target mancante), la grant è revocata con revocation_reason: platform_external. Non ri-concessa automaticamente al rinnovo dell’abbonamento fino a quando il problema della piattaforma sottostante è risolto.
Le grants guidate dall’abbonamento sono idempotenti per (entitlement, customer, subscription); i rinnovi e le riattivazioni non creano grants duplicate. Le grants una tantum sono idempotenti per (entitlement, customer, payment).

​
Crea la tua prima entitlement

1

Open Entitlements

Vai su Entitlements nel tuo dashboard Dodo Payments e fai clic su + per creare una nuova entitlement.
2

Pick an integration

Scegli il tipo di integrazione: Chiave di Licenza, File Digitali, Discord, GitHub, Telegram, Framer o Notion. Per le integrazioni di piattaforma, collega prima il tuo account se non l’hai già fatto.
3

Configure delivery

Compila i campi specifici per l’integrazione. Ad esempio, GitHub chiede un repository e un livello di autorizzazione; Discord chiede un server e un ruolo opzionale; Chiave di Licenza chiede limiti di attivazione e scadenza.
Nuovo modulo di Entitlement con selettore di integrazione e campi di configurazione
4

Save

Salva l’entitlement. Ora puoi collegarla a qualsiasi prodotto.

​
Collegare le Entitlements ai Prodotti

Apri un prodotto, espandi Impostazioni Avanzate → Entitlements & Credits, e seleziona le entitlements che devono essere consegnate quando il prodotto viene acquistato. Un singolo prodotto può consegnare più entitlements contemporaneamente. Ad esempio, un piano Pro può includere una chiave di licenza, accesso a GitHub e un ruolo Discord.
Pannello di selezione dell'entitlement del prodotto che mostra caselle di controllo per ogni entitlement disponibile

​
Esperienza del Cliente

​
Email e portale cliente

I clienti ricevono un’email di consegna dopo l’acquisto contenente la chiave di licenza, i link di download, i link di invito OAuth, o l’invito alla piattaforma, a seconda delle entitlements sul prodotto. Gli stessi dettagli rimangono disponibili indefinitamente dal Customer Portal sotto la loro cronologia ordini.

​
Consegna basata su OAuth

L’accesso per gli abbonati di Discord, GitHub e Notion richiede che il cliente autorizzi Dodo Payments a concedere loro l’accesso. Queste grants rimangono in stato pending fino a quando il cliente completa il flusso OAuth utilizzando il link dalla loro email o dal portale cliente. Una volta autorizzato, la grant passa a delivered e l’accesso alla piattaforma è immediatamente disponibile.

​
Revoche

Le grants revocate vengono rimosse a livello di piattaforma: il ruolo Discord viene rimosso, il collaboratore GitHub viene rimosso, la chiave di licenza viene disabilitata. I clienti vedono il cambiamento riflesso nel portale cliente.
Per i File Digitali, la revoca rimuove l’accesso agli URL presigned in futuro ma non invalida le copie che un cliente ha già scaricato. Piani di contenuto di conseguenza.

​
Gestisci le Grants

Apri qualsiasi entitlement dal dashboard per vedere le sue grants. Il pannello dei dettagli delle grants mostra il totale delle grants, i filtri di stato, le informazioni sul cliente, le date di consegna e un’azione di revoca. Puoi anche gestire le grants in modo programmatico: 
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});

// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
  status: 'delivered',
});

// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
  path_id: 'ent_abc123',
});

​
Gestione API

Create Entitlement

Crea una nuova entitlement di qualsiasi tipo di integrazione.

List Entitlements

Elenca le entitlements con filtraggio per tipo di integrazione.

Get Entitlement

Recupera un’entitlement e la sua configurazione risolta.

Update Entitlement

Aggiorna nome, descrizione o configurazione dell’integrazione.

Delete Entitlement

Elimina soft un’entitlement; le grants esistenti non sono interessate.

Upload File

Carica un file per un’entitlement di File Digitali (fino a 100 MB).

List Grants

Elenca tutte le grants per un’entitlement con filtri di stato e cliente.

Revoke Grant

Revoca manualmente una singola grant.

​
Webhooks

Dodo Payments lancia quattro eventi webhook per il ciclo di vita della grant. Iscriviti a questi eventi per mantenere la tua applicazione sincronizzata con ciò a cui ogni cliente può accedere.
EventoFires quando
entitlement_grant.createdViene creata una nuova grant. Le grants con chiave di licenza arrivano delivered; ogni altra integrazione arriva pending e transita a delivered una volta che la chiamata alla piattaforma ha successo (o, per le integrazioni basate su OAuth, una volta che il cliente autorizza).
entitlement_grant.deliveredLa grant transita alla consegna. Il cliente ha ora accesso.
entitlement_grant.failedLa grant non ha potuto essere consegnata. Ispeziona error_code e error_message.
entitlement_grant.revokedL’accesso è stato ritirato. Ispeziona revocation_reason.

Entitlement Grant Webhook Payloads

Visualizza il payload schema completo, eventi di esempio, e riferimento revocation_reason.

​
Migliori Pratiche

  • Usa una condivisione per canale di consegna. Non condividere un’unica entitlement Discord tra prodotti con intenzioni di ruolo diverse; crea una per ruolo per una revoca pulita.
  • Testa prima in modalità test. Crea l’entitlement, collegala a un prodotto di test, esegui un checkout, e osserva il passaggio della grant attraverso pending → delivered. Conferma che la cancellazione dell’abbonamento di prova revoca la grant.
  • Ascolta entitlement_grant.delivered, non payment.succeeded. Un pagamento può avere successo prima che il fulfillment sia completato (soprattutto per i flussi OAuth). Aspetta l’evento consegnato prima di sbloccare le funzionalità dipendenti nei tuoi sistemi.
  • Tratta entitlement_grant.failed come azionabile. Una grant fallita significa che un cliente ha pagato ma non ha ottenuto l’accesso. Porta ciò alla tua squadra di supporto o avvia una riconcessione.
  • Mappa revocation_reason ai tuoi flussi di retention. Una revoca subscription_on_hold è recuperabile (il cliente può aggiornare la loro carta). Una revoca manual è intenzionale. Trattali diversamente nelle comunicazioni con i clienti.
Last modified on May 14, 2026