Automatically deliver license keys, downloadable files, feature flags, and access to platforms like Discord, GitHub, Telegram, Framer, and Notion when customers pay.
Entitlements turn a successful payment or active subscription into real access: a license key in your customer’s inbox, a feature flag your app checks, a Discord role, a GitHub repository, a Notion template, a Framer remix link, a Telegram chat invite, or a downloadable file bundle. Dodo Payments issues, tracks, and revokes that access automatically as the payment lifecycle changes.
The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.
An entitlement is a reusable definition of something you deliver to a customer: a Pro license key, a “Patrons” Discord role, access to your private GitHub repository, a downloadable e-book bundle. You attach entitlements to products, and Dodo Payments handles the rest.Quando um cliente compra o produto, Dodo Payments cria uma concessão, a emissão desse entitlement para um único cliente. As concessões passam por um pequeno conjunto de status: Pending enquanto a entrega está em andamento, Delivered quando o cliente obtém acesso, Failed se a entrega não puder ser concluída e Revoked quando o acesso é revogado.
Entitlements gate fulfillment (does the customer have access?). Credits gate consumption (how much of it can they use?). Both can be attached to the same product. See Credit-Based Billing for credits.
Grants are driven by the same payment and subscription events you already receive as webhooks. You don’t need to call the grant API yourself for purchases. Dodo Payments creates and revokes grants automatically based on the underlying payment lifecycle.
Uma concessão é criada quando um pagamento é concluído ou uma assinatura se torna ativa. As feature flags vão diretamente para Delivered. As chaves de licença também vão diretamente para Delivered quando o entitlement usa fulfillment_mode: auto (o padrão); em fulfillment_mode: manual, a concessão é criada em Pending sem uma chave até que você forneça uma por meio de Conceder chave de licença. Todas as outras integrações começam em Pending. As integrações baseadas em OAuth (Discord, GitHub, Notion) expõem um oauth_url que o cliente deve visitar para concluir o consentimento; o campo é null em uma concessão recém-criada e é preenchido quando o cliente inicia o fluxo de aceitação pelo e-mail de entrega ou pelo portal do cliente. As integrações diretas da plataforma (Telegram, Framer, Digital Files) permanecem em Pending apenas brevemente enquanto a entrega é provisionada e, depois, fazem a transição para Delivered.
2
Delivered
Quando a entrega é concluída (chave de licença gerada, função atribuída, acesso ao repositório concedido, links de arquivos resolvidos, OAuth concluído), a concessão passa para Delivered e delivered_at é definido.
3
Failed
Se a chamada de integração retornar um erro que não pode ser repetido (token OAuth revogado, permissão negada, arquivo não existe mais), a concessão passa para Failed. Os campos error_code e error_message registram o motivo.
4
Revoked
Quando o acesso é revogado (assinatura cancelada, reembolso emitido ou revogação iniciada pelo merchant), a concessão passa para Revoked. O campo revocation_reason registra o gatilho.
payment.succeeded (pagamento vinculado a uma assinatura)
No-op. As concessões são orientadas pelo evento de assinatura abaixo.
subscription.active
Emitir concessões para quaisquer entitlements anexados que ainda não tenham uma. Conceder novamente quaisquer concessões anteriormente revogadas para a mesma assinatura.
subscription.renewed
No-op. As concessões existentes persistem entre as renovações.
subscription.on_hold
Revogar todas as concessões entregues e pendentes. revocation_reason: subscription_on_hold.
subscription.paused
Revogar todas as concessões entregues e pendentes. revocation_reason: SubscriptionPaused.
subscription.unpaused
Conceder novamente quaisquer concessões anteriormente revogadas para a mesma assinatura, exatamente como subscription.active faz.
Revogar todas as concessões atuais e, em seguida, emitir concessões para os entitlements do novo plano. revocation_reason: plan_changed.
refund.succeeded (pagamento único)
Revogar as concessões desse pagamento. revocation_reason: refund.
Revogação manual via API
Revogar com revocation_reason: manual. As revogações manuais não recebem concessão automática novamente na renovação da assinatura.
Chave de licença desativada
Para concessões de chave de licença, desativar a chave subjacente revoga a concessão com revocation_reason: license_key_disabled. A concessão é reativada automaticamente se a chave for reativada.
Deriva da plataforma detectada
Se o lado da plataforma de uma integração ficar fora de sincronia (uma função do Discord removida manualmente, o GitHub App perder acesso ao repositório ou uma verificação de reconciliação detectar um destino ausente), a concessão será revogada com revocation_reason: platform_external. Ela não receberá concessão automática novamente na renovação da assinatura até que o problema subjacente da plataforma seja resolvido.
Subscription-driven grants are idempotent per (entitlement, customer, subscription); renewals and re-activations do not create duplicate grants. One-time grants are idempotent per (entitlement, customer, payment).
Go to Entitlements in your Dodo Payments dashboard and click + to create a new entitlement.
2
Pick an integration
Escolha o tipo de integração: Chave de licença, Arquivos digitais, Feature Flag, Discord, GitHub, Telegram, Figma, Framer ou Notion. Para integrações de plataforma, conecte sua conta primeiro, caso ainda não tenha feito isso.
3
Configure delivery
Fill in the integration-specific fields. For example, GitHub asks for a repository and a permission level; Discord asks for a server and an optional role; License Key asks for activation limits and expiry.
Creating a GitHub entitlement. Each integration shows the fields it needs.
4
Save
Save the entitlement. You can now attach it to any product.
Open a product, expand Advanced Settings → Entitlements & Credits, and select the entitlements that should be delivered when the product is purchased. A single product can deliver multiple entitlements at once. For example, a Pro plan can include a license key, GitHub access, and a Discord role.
Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.
Customers receive a delivery email after purchase containing the license key, download links, OAuth invitation links, or platform invite, whichever applies to the entitlements on the product. The same details remain available indefinitely from the Customer Portal under their order history.
O acesso de assinantes do Discord, GitHub e Notion exige que o cliente autorize Dodo Payments a conceder acesso a eles. Essas concessões permanecem no status Pending até que o cliente conclua o fluxo de OAuth usando o link do e-mail ou do Customer Portal. Depois que o cliente autoriza, a concessão passa para Delivered e o acesso à plataforma é provisionado imediatamente.
Revoked grants are removed at the platform level: the Discord role is removed, the GitHub collaborator is removed, the license key is disabled. Customers see the change reflected in the customer portal.
For Digital Files, revocation removes access to the presigned URLs going forward but does not invalidate copies a customer has already downloaded. Plan content gating accordingly.
Open any entitlement from the dashboard to see its grants. The grant detail panel shows total grants, status filters, customer information, delivery dates, and a revoke action.You can also manage grants programmatically:
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 fires four webhook events for the grant lifecycle. Subscribe to these events to keep your application in sync with what each customer can access.
Evento
Ocorre quando
entitlement_grant.created
Uma nova concessão é criada. As concessões de chave de licença chegam em Delivered com o fulfillment auto e em Pending com o fulfillment manual; todas as outras integrações chegam em Pending e passam para Delivered quando a chamada à plataforma é bem-sucedida (ou, no caso de integrações baseadas em OAuth, quando o cliente autoriza).
entitlement_grant.delivered
A concessão passa para entregue. O cliente agora tem acesso.
entitlement_grant.failed
Não foi possível entregar a concessão. Consulte error_code e error_message.
entitlement_grant.revoked
O acesso foi revogado. Consulte revocation_reason.
Entitlement Grant Webhook Payloads
View the full payload schema, sample events, and revocation_reason reference.
Use um entitlement por canal de entrega. Não compartilhe um único entitlement do Discord entre produtos com intenções de função diferentes; crie um por função para facilitar a revogação.
Teste primeiro no modo de teste. Crie o entitlement, anexe-o a um produto de teste, faça um checkout e acompanhe a transição da concessão por Pending → Delivered. Confirme que cancelar a assinatura de teste revoga a concessão.
Escute entitlement_grant.delivered, não payment.succeeded. Um pagamento pode ser bem-sucedido antes que o atendimento seja concluído (especialmente em fluxos OAuth). Aguarde o evento de entrega antes de desbloquear os recursos dependentes em seus próprios sistemas.
Trate entitlement_grant.failed como uma ação necessária. Uma concessão malsucedida significa que um cliente pagou, mas não obteve acesso. Encaminhe esses casos à sua equipe de suporte ou acione uma nova concessão.
Mapeie revocation_reason para seus fluxos de retenção. Uma revogação subscription_on_hold é recuperável (o cliente pode atualizar o cartão). Uma revogação manual é intencional. Trate-as de maneira diferente nas comunicações com os clientes.
