Vai al contenuto principale
Le autorizzazioni trasformano un pagamento avvenuto o un abbonamento attivo in vero accesso: una chiave di licenza nella casella di posta del cliente, un flag delle funzionalità che la tua app controlla, un ruolo Discord, un repository GitHub, un modello Notion, un link remix di Framer, un invito alla chat di Telegram o un pacchetto di file scaricabili. Dodo Payments emette, traccia e revoca automaticamente tale accesso in base ai cambiamenti del ciclo di pagamento.
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.

Feature Flags

Limitare l’accesso alle funzionalità nella tua app dopo un acquisto. Consegnato istantaneamente, verificato tramite API, revocato alla cancellazione.

Discord

Concedi a un cliente un ruolo nel tuo server Discord quando acquista. Revocato 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 privato di Telegram dopo l’acquisto.

Framer

Sblocca un link di remix del modello Framer per i clienti paganti.

Notion

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

​
Come funzionano le concessioni

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

​
Ciclo di vita delle concessioni

1

Created

Una concessione viene creata quando un pagamento è completato o un abbonamento diventa attivo. Le chiavi di licenza e i flag delle funzionalità passano direttamente a delivered. Ogni altra integrazione inizia 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, Digital Files) rimangono in pending solo brevemente mentre la consegna viene fornita, quindi passano a delivered.
2

Delivered

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

Failed

Se la chiamata di integrazione restituisce un errore non ripetibile (token OAuth revocato, permesso negato, file non più esistente), la concessione 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 avviata dal commerciante), la concessione passa a revoked. Il campo revocation_reason registra il trigger.

​
Comportamento delle concessioni per evento

EventoComportamento
payment.succeeded (pagamento una tantum)Emissione di una concessione per ogni diritto allegato.
payment.succeeded (pagamento legato all’abbonamento)Nessuna operazione. Le concessioni sono gestite dall’evento di abbonamento qui sotto.
subscription.activeEmissione di concessioni per tutti i diritti allegati che non ne hanno già una. Concessione di nuovo eventuali concessioni precedentemente revocate per lo stesso abbonamento.
subscription.renewedNessuna operazione. Le concessioni esistenti persistono nei rinnovi.
subscription.on_holdRevoca di tutte le concessioni consegnate e in sospeso. revocation_reason: subscription_on_hold.
subscription.cancelledRevoca di tutto. revocation_reason: subscription_cancelled.
subscription.expiredRevoca di tutto. revocation_reason: subscription_expired.
subscription.plan_changedRevoca di tutte le concessioni correnti, quindi emissione di concessioni per i diritti del nuovo piano. revocation_reason: plan_changed.
refund.succeeded (pagamento una tantum)Revoca delle concessioni per quel pagamento. revocation_reason: refund.
Revoca manuale APIRevoca con revocation_reason: manual. Le revoche manuali non vengono riassegnate automaticamente alla rinnovazione dell’abbonamento.
Chiave di licenza disabilitataPer le concessioni con chiave di licenza, disabilitare la chiave sottostante revoca la concessione con revocation_reason: license_key_disabled. La concessione è riattivata automaticamente se la chiave è riattivata.
Drift della piattaforma rilevatoSe il lato piattaforma di un’integrazione si disallinea (un ruolo Discord rimosso manualmente, l’app GitHub perde l’accesso al repository o un passaggio di riconciliazione rileva un target mancante), la concessione è revocata con revocation_reason: platform_external. Non viene riassegnata automaticamente alla rinnovazione dell’abbonamento fino a quando il problema sottostante della piattaforma non viene risolto.
Le concessioni basate su abbonamento sono idempotenti per (entitlement, customer, subscription); i rinnovi e le riattivazioni non creano concessioni duplicate. Le concessioni una tantum sono idempotenti per (entitlement, customer, payment).

​
Creare il tuo primo diritto

1

Open Entitlements

Vai su Diritti nel tuo pannello di Dodo Payments e fai clic su + per creare un nuovo diritto.
2

Pick an integration

Scegli il tipo di integrazione: Chiave di licenza, File digitali, Flag delle funzionalità, Discord, GitHub, Telegram, Framer o Notion. Per le integrazioni sulla piattaforma, connetti prima il tuo account se non lo hai già fatto.
3

Configure delivery

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

Save

Salva il diritto. Ora puoi allegarlo a qualsiasi prodotto.

​
Allegare diritti ai prodotti

Apri un prodotto, espandi Impostazioni avanzate → Diritti e Crediti e seleziona i diritti che devono essere consegnati quando il prodotto viene acquistato. Un singolo prodotto può consegnare più diritti contemporaneamente. Ad esempio, un piano Pro può includere una chiave di licenza, l’accesso a GitHub e un ruolo Discord.
Pannello di selezione dei diritti del prodotto che mostra le caselle di controllo per ogni diritto disponibile

​
Esperienza del cliente

​
E-mail e portale clienti

I clienti ricevono un’email di consegna dopo l’acquisto contenente la chiave di licenza, i link per il download, i link di invito OAuth o inviti alla piattaforma, a seconda di ciò che si applica ai diritti sul prodotto. Gli stessi dettagli rimangono disponibili indefinitamente dal Portale Clienti sotto la loro cronologia ordini.

​
Consegna basata su OAuth

L’accesso ai sottoscrittori di Discord, GitHub e Notion richiede che il cliente autorizzi Dodo Payments a concedergli l’accesso. Queste concessioni rimangono in stato pending fino a quando il cliente non completa il flusso OAuth utilizzando il link dalla loro email o portale clienti. Una volta autorizzati, la concessione passa a delivered e l’accesso alla piattaforma viene fornito immediatamente.

​
Revoca

Le concessioni 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 clienti.
Per i file digitali, la revoca rimuove l’accesso agli URL presigned nel futuro ma non invalida le copie già scaricate dal cliente. Pianifica il contenuto del piano di conseguenza.

​
Gestisci le concessioni

Apri qualsiasi diritto dalla dashboard per vedere le sue concessioni. Il pannello dettagli concessioni mostra le concessioni totali, i filtri di stato, le informazioni sui clienti, le date di consegna e un’azione di revoca. Puoi anche gestire le concessioni 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', {
  id: 'ent_abc123',
});

client.entitlements.grants.list(
    "ent_abc123",
    status="Delivered",
)

client.entitlements.grants.revoke(
    "grant_xyz789",
    id="ent_abc123",
)

grants, _ := client.Entitlements.Grants.List(
  ctx, "ent_abc123",
  dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)

_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")

​
Gestione API

Create Entitlement

Crea un nuovo diritto di qualsiasi tipo di integrazione.

List Entitlements

Elenca i diritti con filtro per tipo di integrazione.

Get Entitlement

Recupera un diritto e la sua configurazione risolta.

Update Entitlement

Aggiorna nome, descrizione o configurazione dell’integrazione.

Delete Entitlement

Elimina un diritto in modo soft; le concessioni esistenti non sono influenzate.

Upload File

Carica un file in un diritto di File Digitali (fino a 500 MiB).

List Grants

Elenca tutte le concessioni per un diritto con filtri di stato e clienti.

Revoke Grant

Revoca manualmente una singola concessione.

​
Webhooks

Dodo Payments attiva quattro eventi webhook per il ciclo di vita delle concessioni. Iscriviti a questi eventi per mantenere la tua applicazione sincronizzata con ciò che ciascun cliente può accedere.
EventoSi attiva quando
entitlement_grant.createdViene creata una nuova concessione. Le concessioni 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 concessione passa a consegnata. Il cliente ora ha accesso.
entitlement_grant.failedLa concessione non ha potuto essere consegnata. Controlla error_code e error_message.
entitlement_grant.revokedL’accesso è stato ritirato. Controlla revocation_reason.

Entitlement Grant Webhook Payloads

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

​
Pratiche consigliate

  • Usa un diritto per canale di consegna. Non condividere un solo diritto Discord tra prodotti con diverse intenzioni di ruolo; creane uno per ruolo per una revoca pulita.
  • Testa prima in modalità test. Crea il diritto, allegalo a un prodotto di test, esegui un checkout e osserva la transizione della concessione tramite pending → delivered. Conferma che la cancellazione dell’abbonamento di test revoca la concessione.
  • Ascolta entitlement_grant.delivered, non payment.succeeded. Un pagamento può avere successo prima che la consegna finisca (soprattutto per flussi OAuth). Aspetta l’evento consegnato prima di sbloccare le funzionalità dipendenti nei tuoi sistemi.
  • Tratta entitlement_grant.failed come attuabile. Una concessione fallita significa che un cliente ha pagato ma non ha ottenuto accesso. Metti questi in evidenza al tuo team di supporto o attiva un riesame.
  • Mappa revocation_reason ai tuoi flussi di conservazione. Una revoca subscription_on_hold è recuperabile (il cliente potrebbe aggiornare la propria carta). Una revoca manual è intenzionale. Trattale diversamente nelle comunicazioni con il cliente.
Ultima modifica il 9 luglio 2026