Fornisci automaticamente chiavi di licenza, file scaricabili, flag delle funzionalità e accesso a piattaforme come Discord, GitHub, Telegram, Framer e Notion quando i clienti pagano.
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.
The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.
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 un grant, ovvero l’assegnazione di tale entitlement a un singolo cliente. I grant attraversano un insieme ristretto di stati: Pending mentre la consegna è in corso, Delivered quando il cliente ottiene l’accesso, Failed se la consegna non può essere completata e Revoked quando l’accesso viene revocato.
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.
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.
Una concessione viene creata quando un pagamento viene completato o un abbonamento diventa attivo. I flag delle funzionalità passano direttamente a Delivered. Anche le chiavi di licenza passano direttamente a Delivered quando l’entitlement utilizza fulfillment_mode: auto (il valore predefinito); con fulfillment_mode: manual la concessione viene creata in Pending senza chiave, finché non ne fornisci una tramite Esegui il fulfilment della concessione della chiave di licenza. Ogni altra integrazione inizia in Pending. Le integrazioni basate su OAuth (Discord, GitHub, Notion) espongono un oauth_url che il cliente deve visitare per completare il consenso; il campo è null in una concessione appena creata e viene popolato quando il cliente avvia il flusso di accettazione dalla propria email di consegna o dal customer portal. Le integrazioni dirette alla piattaforma (Telegram, Framer, Digital Files) rimangono in Pending solo brevemente, mentre viene predisposta la consegna, poi passano a Delivered.
2
Delivered
Quando la consegna è completata (license key generata, ruolo assegnato, accesso al repository concesso, link ai file risolti, OAuth completato), il grant passa a Delivered e delivered_at viene impostato.
3
Failed
Se la chiamata all’integrazione restituisce un errore non ritentabile (token OAuth revocato, autorizzazione negata, file non più esistente), il grant passa a Failed. I campi error_code e error_message contengono il motivo.
4
Revoked
Quando l’accesso viene revocato (abbonamento annullato, rimborso emesso o revoca avviata dal merchant), il grant passa a Revoked. Il campo revocation_reason registra il trigger.
Emette una concessione per ogni entitlement associato.
payment.succeeded (pagamento collegato a un abbonamento)
No-op. Le concessioni sono determinate dall’evento dell’abbonamento riportato di seguito.
subscription.active
Emette concessioni per tutti gli entitlement associati che non ne hanno già una. Emette nuovamente le concessioni precedentemente revocate per lo stesso abbonamento.
subscription.renewed
No-op. Le concessioni esistenti persistono tra i rinnovi.
subscription.on_hold
Revoca tutte le concessioni consegnate e in sospeso. revocation_reason: subscription_on_hold.
subscription.paused
Revoca tutte le concessioni consegnate e in sospeso. revocation_reason: SubscriptionPaused.
subscription.unpaused
Emette nuovamente le concessioni precedentemente revocate per lo stesso abbonamento, esattamente come fa subscription.active.
Revoca tutte le concessioni attuali, quindi emette concessioni per gli entitlement del nuovo piano. revocation_reason: plan_changed.
refund.succeeded (pagamento una tantum)
Revoca le concessioni per quel pagamento. revocation_reason: refund.
Revoca API manuale
Revoca con revocation_reason: manual. Le revoche manuali non vengono emesse nuovamente automaticamente al rinnovo dell’abbonamento.
Chiave di licenza disabilitata
Per le concessioni basate su chiavi di licenza, la disabilitazione della chiave sottostante revoca la concessione con revocation_reason: license_key_disabled. La concessione viene riattivata automaticamente se la chiave viene riabilitata.
Deriva della piattaforma rilevata
Se il lato della piattaforma di un’integrazione perde la sincronizzazione (un ruolo Discord rimosso manualmente, l’App GitHub che perde l’accesso al repository o un passaggio di riconciliazione che rileva una destinazione mancante), la concessione viene revocata con revocation_reason: platform_external. Non viene emessa nuovamente automaticamente al rinnovo dell’abbonamento finché il problema della piattaforma sottostante 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).
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: License Key, Digital Files, Feature Flag, Discord, GitHub, Telegram, Figma, Framer o Notion. Per le integrazioni della piattaforma, collega prima il tuo account se non l’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.
Creating a GitHub entitlement. Each integration shows the fields it needs.
4
Save
Salva il diritto. Ora puoi allegarlo a qualsiasi prodotto.
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.
Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.
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.
L’accesso degli abbonati a Discord, GitHub e Notion richiede che il cliente autorizzi Dodo Payments a concedere loro l’accesso. Questi grant rimangono nello stato Pending finché il cliente non completa il flusso OAuth utilizzando il link contenuto nell’email o nel Customer Portal. Dopo l’autorizzazione, il grant passa a Delivered e l’accesso alla piattaforma viene configurato immediatamente.
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.
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 entitlementconst grants = await client.entitlements.grants.list('ent_abc123', { status: 'Delivered',});// Revoke a single grantawait client.entitlements.grants.revoke('entg_xyz789', { id: 'ent_abc123',});
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.
Evento
Si attiva quando
entitlement_grant.created
Viene creato un nuovo grant. I grant con license key arrivano Delivered con il fulfillment auto e Pending con il fulfillment manual; tutte le altre integrazioni arrivano Pending e passano a Delivered quando la chiamata alla piattaforma ha esito positivo (oppure, per le integrazioni basate su OAuth, quando il cliente autorizza).
entitlement_grant.delivered
Il grant passa allo stato delivered. Il cliente ora ha accesso.
entitlement_grant.failed
Il grant non ha potuto essere consegnato. Esamina error_code e error_message.
entitlement_grant.revoked
L’accesso è stato revocato. Esamina revocation_reason.
Entitlement Grant Webhook Payloads
Visualizza lo schema del payload completo, eventi di esempio e il riferimento revocation_reason.
Usa un entitlement per ogni canale di consegna. Non condividere un singolo entitlement Discord tra prodotti con intenzioni di ruolo diverse; creane uno per ruolo per semplificare la revoca.
Esegui prima i test in modalità di test. Crea l’entitlement, collegalo a un prodotto di test, esegui un checkout e osserva la transizione della concessione attraverso Pending → Delivered. Conferma che l’annullamento dell’abbonamento di test revochi la concessione.
Ascolta entitlement_grant.delivered, non payment.succeeded. Un pagamento può andare a buon fine prima che il fulfilment sia completato (soprattutto nei flussi OAuth). Attendi l’evento di consegna prima di sbloccare le funzionalità dipendenti nei tuoi sistemi.
Considera entitlement_grant.failed come un evento che richiede un’azione. Una concessione non riuscita significa che un cliente ha pagato ma non ha ottenuto l’accesso. Segnala questi casi al team di supporto o attiva una nuova concessione.
Associa revocation_reason ai tuoi flussi di fidelizzazione. Una revoca subscription_on_hold è recuperabile (il cliente potrebbe aggiornare la propria carta). Una revoca manual è intenzionale. Gestiscile in modo diverso nelle comunicazioni ai clienti.
