Entrega automáticamente claves de licencia, archivos descargables, feature flags y acceso a Discord, GitHub, Telegram, Framer y Notion cuando los clientes pagan.
Los entitlements convierten un pago completado o una suscripción activa en acceso: una clave de licencia en la bandeja de entrada de tu cliente, un feature flag que comprueba tu aplicación, un rol de Discord, un repositorio de GitHub, una plantilla de Notion, un enlace de remix de Framer, una invitación a un chat de Telegram o un paquete de archivos descargables. Dodo Payments emite, realiza el seguimiento y revoca ese acceso automáticamente a medida que cambia el ciclo de vida del pago.
The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.
Un entitlement es una definición reutilizable de algo que entregas a un cliente, como una clave de licencia Pro, un rol de Discord llamado “Patrons”, acceso a tu repositorio privado de GitHub o un paquete de libros electrónicos descargables. Asocias entitlements a los productos y Dodo Payments los entrega cuando un cliente paga.Cuando un cliente compra el producto, Dodo Payments crea un grant: la emisión de ese entitlement para un cliente. Un grant tiene uno de cuatro estados: Pending mientras la entrega está en curso, Delivered cuando el cliente obtiene acceso, Failed si la entrega no pudo completarse y Revoked cuando se retira el acceso.
Los entitlements controlan el fulfillment (¿el cliente tiene acceso?). Los créditos controlan el consumo (¿cuánto puede usar?). Puedes asociar ambos al mismo producto. Consulta Facturación basada en créditos para obtener información sobre los créditos.
Los grants siguen los mismos eventos de pago y suscripción que recibes como webhooks. Dodo Payments crea y revoca grants automáticamente para las compras, según el ciclo de vida del pago, por lo que no tienes que llamar a la grant API.
Dodo Payments crea un grant cuando se completa un pago o una suscripción pasa a estar activa. Los grants de feature flags comienzan como Delivered. Los grants de claves de licencia también comienzan como Delivered cuando el entitlement usa fulfillment_mode: auto (el valor predeterminado). Con fulfillment_mode: manual, el grant comienza como Pending sin clave hasta que proporciones una mediante Completar grant de clave de licencia. Todas las demás integraciones comienzan como Pending.Las integraciones basadas en OAuth (Discord, GitHub y Notion) exponen un oauth_url que el cliente visita para dar su consentimiento. Dodo Payments intenta generar esta URL al crear el grant. Si falla, el campo permanece como null hasta que el cliente inicia el flujo de aceptación desde su correo electrónico de entrega o el Customer Portal. Las integraciones directas de la plataforma (Telegram, Framer y Digital Files) permanecen como Pending solo mientras se aprovisiona la entrega; después pasan a Delivered.
2
Delivered
Cuando se completa la entrega, el grant pasa a Delivered y se establece delivered_at. La entrega se completa cuando se genera la clave de licencia, se asigna el rol, se concede el acceso al repositorio, se resuelven los enlaces de archivos o finaliza el flujo de OAuth.
3
Failed
Si la llamada de integración devuelve un error no reintentable, como un token de OAuth revocado, un permiso denegado o un archivo que ya no existe, el grant pasa a Failed. Los campos error_code y error_message registran el motivo.
4
Revoked
Cuando se retira el acceso, por ejemplo porque se cancela una suscripción, se emite un reembolso o revocas el grant, el grant pasa a Revoked. El campo revocation_reason registra el desencadenante.
Cada evento de pago y suscripción modifica los grants de la siguiente manera:
Evento
Comportamiento
payment.succeeded (pago único)
Emite un grant por cada entitlement asociado. Un entitlement de License Key emite un grant por cada clave.
payment.succeeded (pago asociado a una suscripción)
Sin cambios. Los eventos de suscripción siguientes controlan estos grants.
subscription.active
Emite grants para los entitlements asociados que aún no tengan uno y vuelve a emitir los grants revocados anteriormente para la misma suscripción. Los grants revocados con manual, refund o platform_external no vuelven a emitirse.
subscription.renewed
Sin cambios. Los grants existentes persisten durante las renovaciones.
subscription.past_due
Sin cambios. Los grants permanecen entregados durante todo el periodo de gracia.
subscription.on_hold
Revoca todos los grants entregados y pendientes con revocation_reason: subscription_on_hold.
subscription.paused
Revoca todos los grants entregados y pendientes con revocation_reason: SubscriptionPaused. A diferencia de los demás motivos de suscripción, este valor usa PascalCase, así que debes coincidir exactamente con él.
subscription.unpaused
Vuelve a emitir los grants revocados anteriormente para la misma suscripción, igual que subscription.active.
subscription.cancelled
Revoca todos los grants con revocation_reason: subscription_cancelled.
subscription.expired
Revoca todos los grants con revocation_reason: subscription_expired.
subscription.plan_changed
Revoca todos los grants actuales con revocation_reason: plan_changed y después emite grants para los entitlements del nuevo plan.
refund.succeeded (pago único)
Revoca los grants de ese pago con revocation_reason: refund.
Revocación manual mediante la API
Revoca el grant con revocation_reason: manual. Las revocaciones manuales no vuelven a emitirse automáticamente durante la renovación de una suscripción.
Clave de licencia desactivada
Para los grants de claves de licencia, desactivar la clave subyacente revoca el grant con revocation_reason: license_key_disabled. Al volver a activar la clave, el grant se restaura automáticamente.
Deriva de la plataforma detectada
Si el lado de la plataforma de una integración deja de estar sincronizado, por ejemplo, porque se eliminó manualmente un rol de Discord, la GitHub App perdió el acceso al repositorio o una ejecución de conciliación detectó que falta el destino, Dodo Payments revoca el grant con revocation_reason: platform_external. No vuelve a emitirse automáticamente durante la renovación de la suscripción hasta que se resuelva el problema de la plataforma.
Los grants controlados por suscripciones son idempotentes por (entitlement, customer, subscription), por lo que las renovaciones y reactivaciones no crean grants duplicados. Los grants de pago único son idempotentes por (entitlement, customer, payment).
Ve a Entitlements en el dashboard y haz clic en + para crear un entitlement.
2
Pick an Integration
Elige el tipo de integración: License Key, Digital Files, Feature Flag, Discord, GitHub, Telegram, Figma, Framer o Notion. Para una integración de plataforma, conecta primero tu cuenta si aún no lo has hecho.
3
Configure Delivery
Completa los campos de la integración. Por ejemplo, GitHub solicita un repositorio y un nivel de permisos; Discord solicita un servidor y un rol opcional; y License Key solicita un límite de activaciones y una duración de la licencia.
Creating a GitHub entitlement. Each integration shows the fields it needs.
4
Save
Haz clic en Create Entitlement. Ahora puedes asociar el entitlement a cualquier producto.
Abre un producto, ve a su sección Entitlements y selecciona los entitlements que se entregarán cuando se compre el producto. Un producto puede entregar varios entitlements a la vez. Por ejemplo, un plan Pro puede incluir una clave de licencia, acceso a GitHub y un rol de Discord.
Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.
Después de una compra, el cliente recibe un correo electrónico de entrega con la clave de licencia, los enlaces de descarga, los enlaces de invitación de OAuth o la invitación de plataforma correspondiente a los entitlements del producto. Los mismos detalles siguen disponibles en el Customer Portal, dentro del historial de pedidos, mientras el grant esté activo.
El acceso de suscriptores a Discord, GitHub y Notion requiere que el cliente autorice a Dodo Payments a conceder dicho acceso. Estos grants permanecen como Pending hasta que el cliente completa el flujo de OAuth desde el enlace de su correo electrónico o el Customer Portal. Después de que el cliente autoriza, el grant pasa a Delivered y Dodo Payments aprovisiona el acceso a la plataforma.
Cuando se revoca un grant, Dodo Payments elimina el acceso en la plataforma: elimina el rol de Discord, elimina al colaborador de GitHub o desactiva la clave de licencia. El cliente ve el cambio en el Customer Portal.
Para Digital Files, la revocación detiene las nuevas URL de descarga presigned, pero no invalida las copias que el cliente ya haya descargado. Tenlo en cuenta al planificar el control de acceso a tu contenido.
Abre cualquier entitlement desde el dashboard para ver sus grants. El panel de detalles muestra el total concedido, un filtro de estado y una fila por grant con el cliente, la fecha de acceso, el estado y una acción Revoke.Para gestionar grants mediante programación, enuméralos con el filtro status y revoca un único grant por 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 envía cuatro eventos de webhook para el ciclo de vida del grant. Suscríbete a ellos para mantener tu aplicación sincronizada con lo que cada cliente puede usar.
Evento
Se activa cuando
entitlement_grant.created
Se crea un grant. Los grants de claves de licencia completados automáticamente y los grants de feature flags llegan como Delivered. Los grants de claves de licencia completados manualmente y todas las demás integraciones llegan como Pending y pasan a Delivered cuando la llamada de la plataforma se completa correctamente o, en el caso de las integraciones basadas en OAuth, cuando el cliente autoriza.
entitlement_grant.delivered
Un grant existente pasa a Delivered, por lo que el cliente obtiene acceso. Un grant que está en Delivered al crearse solo activa created.
entitlement_grant.failed
No se pudo entregar el grant. Comprueba error_code y error_message.
entitlement_grant.revoked
Se ha retirado el acceso. Comprueba revocation_reason.
Entitlement Grant Webhook Payloads
Consulta el esquema completo del payload, eventos de ejemplo y la referencia de revocation_reason.
Usa un entitlement por canal de entrega. No compartas un entitlement de Discord entre productos con distintas funciones de rol. Crea un entitlement por rol para que la revocación sea clara.
Prueba primero en modo de prueba. Crea el entitlement, asígnalo a un producto de prueba, realiza un checkout y observa cómo el grant pasa de Pending a Delivered. Después, cancela la suscripción de prueba y confirma que el grant se revoca.
Escucha entitlement_grant.delivered, no payment.succeeded. Un pago puede completarse antes de que finalice el fulfillment, especialmente en los flujos de OAuth. Espera a que el grant alcance Delivered antes de desbloquear funciones dependientes en tus propios sistemas. Un grant que se entrega al crearse, como una clave de licencia completada automáticamente o un feature flag, llega como entitlement_grant.created con status: "Delivered".
Trata entitlement_grant.failed como una acción necesaria. Un grant fallido significa que un cliente pagó pero no obtuvo acceso. Muestra estos grants a tu equipo de soporte o activa una nueva emisión.
Asocia revocation_reason a tus flujos de retención. Una revocación subscription_on_hold se puede recuperar porque el cliente podría actualizar su tarjeta. Una revocación manual es intencionada. Trátalas de forma distinta en los mensajes a los clientes.
No revoques el acceso en subscription.past_due. Ese evento abre un periodo de gracia y el cliente conserva el acceso hasta que finaliza la ventana. Espera a subscription.on_hold o subscription.cancelled.
