Consegna automaticamente chiavi di licenza, file scaricabili, feature flag e accesso a Discord, GitHub, Telegram, Framer e Notion quando i clienti effettuano un pagamento.
Gli entitlement trasformano un pagamento completato o un abbonamento attivo in accesso: una chiave di licenza nella casella di posta del cliente, un feature flag verificato dalla tua app, un ruolo Discord, un repository GitHub, un template Notion, un link per il remix su Framer, un invito a una chat Telegram o un pacchetto di file scaricabili. Dodo Payments emette, monitora e revoca automaticamente questo accesso quando cambia il ciclo di vita del 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, ad esempio una chiave di licenza Pro, un ruolo Discord “Patrons”, l’accesso al tuo repository GitHub privato o un pacchetto di e-book scaricabili. Colleghi gli entitlement ai prodotti e Dodo Payments li consegna quando un cliente paga.Quando un cliente acquista il prodotto, Dodo Payments crea un grant: l’emissione di quell’entitlement per un singolo cliente. Un grant ha uno di quattro stati: Pending mentre la consegna è in corso, Delivered quando il cliente ha ottenuto l’accesso, Failed se la consegna non è stata completata e Revoked quando l’accesso viene ritirato.
Gli entitlement regolano il fulfillment (il cliente ha accesso?). I crediti regolano il consumo (quanto può utilizzarne?). Puoi collegare entrambi allo stesso prodotto. Consulta Credit-Based Billing per i crediti.
I grant seguono gli stessi eventi di pagamento e abbonamento che ricevi come webhook. Dodo Payments crea e revoca automaticamente i grant per gli acquisti, in base al ciclo di vita del pagamento, quindi non devi chiamare personalmente l’API dei grant.
Dodo Payments crea un grant quando un pagamento viene completato o un abbonamento diventa attivo. I grant dei feature flag iniziano come Delivered. Anche i grant delle chiavi di licenza iniziano come Delivered quando l’entitlement utilizza fulfillment_mode: auto (il valore predefinito). Con fulfillment_mode: manual, il grant inizia come Pending senza chiave, finché non ne fornisci una tramite Fulfill License Key Grant. Ogni altra integrazione inizia come Pending.Le integrazioni basate su OAuth (Discord, GitHub, Notion) espongono un oauth_url che il cliente visita per prestare il consenso. Dodo Payments tenta di generare questo URL quando crea il grant. Se l’operazione fallisce, il campo rimane null finché il cliente non avvia il flusso di accettazione dall’e-mail di consegna o dal Customer Portal. Le integrazioni dirette alla piattaforma (Telegram, Framer, Digital Files) rimangono Pending solo mentre la consegna viene predisposta, poi passano a Delivered.
2
Delivered
Quando la consegna viene completata, il grant passa a Delivered e viene impostato delivered_at. La consegna è completa quando viene generata la chiave di licenza, viene assegnato il ruolo, viene concesso l’accesso al repository, vengono risolti i link ai file o viene completato il flusso OAuth.
3
Failed
Se la chiamata all’integrazione restituisce un errore non ritentabile, come un token OAuth revocato, un’autorizzazione negata o un file che non esiste più, il grant passa a Failed. I campi error_code e error_message registrano il motivo.
4
Revoked
Quando l’accesso viene ritirato, ad esempio perché un abbonamento viene cancellato, viene emesso un rimborso o revochi il grant, il grant passa a Revoked. Il campo revocation_reason registra il fattore scatenante.
Ogni evento di pagamento e abbonamento modifica i grant come segue:
Evento
Comportamento
payment.succeeded (pagamento una tantum)
Emette un grant per ogni entitlement collegato. Un entitlement License Key emette un grant per ogni chiave.
payment.succeeded (pagamento collegato a un abbonamento)
Nessuna modifica. Gli eventi dell’abbonamento riportati di seguito gestiscono questi grant.
subscription.active
Emette grant per gli entitlement collegati che non ne hanno ancora uno e riemette i grant precedentemente revocati per lo stesso abbonamento. I grant revocati con manual, refund o platform_external non vengono riemessi.
subscription.renewed
Nessuna modifica. I grant esistenti persistono tra i rinnovi.
Revoca tutti i grant consegnati e in sospeso con revocation_reason: subscription_on_hold.
subscription.paused
Revoca tutti i grant consegnati e in sospeso con revocation_reason: SubscriptionPaused. A differenza degli altri motivi dell’abbonamento, questo valore usa PascalCase, quindi deve corrispondere esattamente.
subscription.unpaused
Riemette i grant precedentemente revocati per lo stesso abbonamento, come fa subscription.active.
subscription.cancelled
Revoca tutti i grant con revocation_reason: subscription_cancelled.
subscription.expired
Revoca tutti i grant con revocation_reason: subscription_expired.
subscription.plan_changed
Revoca tutti i grant attuali con revocation_reason: plan_changed, quindi emette grant per gli entitlement del nuovo piano.
refund.succeeded (pagamento una tantum)
Revoca i grant relativi a quel pagamento con revocation_reason: refund.
Revoca manuale tramite API
Revoca il grant con revocation_reason: manual. Le revoche manuali non vengono riemesse automaticamente al rinnovo dell’abbonamento.
Chiave di licenza disabilitata
Per i grant delle chiavi di licenza, la disabilitazione della chiave sottostante revoca il grant con revocation_reason: license_key_disabled. Riabilitando la chiave, il grant viene ripristinato automaticamente.
Deriva della piattaforma rilevata
Se il lato della piattaforma di un’integrazione non è più sincronizzato, ad esempio perché un ruolo Discord è stato rimosso manualmente, la GitHub App ha perso l’accesso al repository o un controllo di riconciliazione ha rilevato una destinazione mancante, Dodo Payments revoca il grant con revocation_reason: platform_external. Non viene riemesso automaticamente al rinnovo dell’abbonamento finché il problema della piattaforma non viene risolto.
I grant gestiti dagli abbonamenti sono idempotenti per (entitlement, customer, subscription), quindi rinnovi e riattivazioni non creano grant duplicati. I grant una tantum sono idempotenti per (entitlement, customer, payment).
Vai alla sezione Entitlements nella dashboard e fai clic su + per creare un entitlement.
2
Pick an Integration
Scegli il tipo di integrazione: License Key, Digital Files, Feature Flag, Discord, GitHub, Telegram, Figma, Framer o Notion. Per un’integrazione di piattaforma, collega prima il tuo account se non l’hai già fatto.
3
Configure Delivery
Compila i campi dell’integrazione. Ad esempio, GitHub richiede un repository e un livello di autorizzazione, Discord richiede un server e un ruolo opzionale, mentre License Key richiede un limite di attivazioni e una durata della licenza.
Creating a GitHub entitlement. Each integration shows the fields it needs.
4
Save
Fai clic su Create Entitlement. Ora puoi collegare l’entitlement a qualsiasi prodotto.
Apri un prodotto, vai alla sezione Entitlements e seleziona gli entitlement da consegnare quando il prodotto viene acquistato. Un prodotto può consegnare diversi entitlement 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.
Dopo un acquisto, il cliente riceve un’e-mail di consegna con la chiave di licenza, i link per il download, i link di invito OAuth o l’invito alla piattaforma applicabile agli entitlement del prodotto. Gli stessi dettagli rimangono disponibili nel Customer Portal, nella cronologia degli ordini, finché il grant è attivo.
L’accesso degli abbonati a Discord, GitHub e Notion richiede che il cliente autorizzi Dodo Payments a concedere tale accesso. Questi grant rimangono Pending finché il cliente non completa il flusso OAuth dal link nell’e-mail o nel Customer Portal. Dopo l’autorizzazione del cliente, il grant passa a Delivered e Dodo Payments configura l’accesso alla piattaforma.
Quando un grant viene revocato, Dodo Payments rimuove l’accesso sulla piattaforma: rimuove il ruolo Discord, rimuove il collaboratore GitHub o disabilita la chiave di licenza. Il cliente vede la modifica nel Customer Portal.
Per Digital Files, la revoca impedisce la generazione di nuovi URL di download presigned, ma non invalida le copie che un cliente ha già scaricato. Tienilo presente quando pianifichi la gestione degli accessi ai tuoi contenuti.
Apri qualsiasi entitlement dalla dashboard per visualizzarne i grant. Il pannello dei dettagli mostra il totale dei grant, un filtro per stato e una riga per ogni grant con il cliente, la data di accesso, lo stato e un’azione Revoke.Per gestire i grant a livello programmatico, elencali con il filtro status e revoca un singolo grant tramite ID:
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 invia quattro eventi webhook per il ciclo di vita dei grant. Iscriviti a questi eventi per mantenere la tua applicazione sincronizzata con ciò a cui ogni cliente può accedere.
Evento
Si attiva quando
entitlement_grant.created
Viene creato un grant. I grant delle chiavi di licenza completati automaticamente e i grant dei feature flag arrivano Delivered. I grant delle chiavi di licenza completati manualmente e ogni altra integrazione arrivano Pending, poi passano a Delivered quando la chiamata alla piattaforma ha esito positivo o, per le integrazioni basate su OAuth, quando il cliente autorizza.
entitlement_grant.delivered
Un grant esistente passa a Delivered, quindi il cliente ottiene l’accesso. Un grant che è Delivered alla creazione attiva solo created.
entitlement_grant.failed
Il grant non è stato consegnato. Esamina error_code e error_message.
entitlement_grant.revoked
L’accesso è stato ritirato. Esamina revocation_reason.
Entitlement Grant Webhook Payloads
Visualizza lo schema completo del payload, gli eventi di esempio e il riferimento revocation_reason.
Usa un entitlement per ogni canale di consegna. Non condividere un entitlement Discord tra prodotti con ruoli diversi. Crea un entitlement per ogni ruolo, così la revoca rimane pulita.
Esegui prima i test in modalità test. Crea l’entitlement, collegalo a un prodotto di test, esegui un checkout e osserva il grant passare da Pending a Delivered. Poi cancella l’abbonamento di test e verifica che il grant venga revocato.
Ascolta entitlement_grant.delivered, non payment.succeeded. Un pagamento può avere esito positivo prima che il fulfillment sia completato, soprattutto nei flussi OAuth. Attendi che il grant raggiunga Delivered prima di sbloccare le funzionalità dipendenti nei tuoi sistemi. Un grant consegnato alla creazione, come una chiave di licenza completata automaticamente o un feature flag, arriva come entitlement_grant.created con status: "Delivered".
Considera entitlement_grant.failed un evento che richiede un’azione. Un grant fallito significa che un cliente ha pagato ma non ha ottenuto l’accesso. Segnala questi grant al team di supporto o attiva una nuova emissione.
Collega revocation_reason ai tuoi flussi di fidelizzazione. Una revoca subscription_on_hold è recuperabile, perché il cliente potrebbe aggiornare la propria carta. Una revoca manual è intenzionale. Gestiscile in modo diverso nei messaggi ai clienti.
Non revocare l’accesso su subscription.past_due. Questo evento apre un periodo di tolleranza e il cliente mantiene l’accesso fino alla fine della finestra. Attendi subscription.on_hold o subscription.cancelled.
