Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Entitlements transformam um pagamento bem-sucedido ou assinatura ativa em acesso real: uma chave de licença na caixa de entrada do seu cliente, um papel do Discord, um repositório GitHub, um modelo Notion, um link de remix de Framer, um convite para chat no Telegram ou um pacote de arquivos para download. O Dodo Payments emite, rastreia e revoga esse acesso automaticamente conforme o ciclo de pagamento muda.
Painel de entitlements com uma lista de entitlements à esquerda e atividade de concessão à direita

​
O que são Entitlements?

Um entitlement é uma definição reutilizável de algo que você entrega a um cliente: uma chave de licença Pro, um papel “Patrons” no Discord, acesso ao seu repositório privado no GitHub, um pacote de e-books para download. Você anexa entitlements a produtos, e o Dodo Payments cuida do resto. Quando um cliente compra o produto, o Dodo Payments cria uma grant, uma emissão única desse entitlement para o cliente. As grants passam por um pequeno conjunto de status: pending enquanto a entrega está em andamento, delivered quando o cliente tem acesso, failed se a entrega não puder ser concluída, e revoked quando o acesso é retirado.
Entitlements controlam o fulfillment (o cliente tem acesso?). Créditos controlam o consumo (quanto eles podem usar?). Ambos podem ser anexados ao mesmo produto. Veja Faturamento Baseado em Créditos para créditos.

​
Integrações Disponíveis

O Dodo Payments entrega cada entitlement por meio de uma integração dedicada. Escolha a integração que corresponde ao que você vende.

License Keys

Gere chaves de licença únicas com limites de ativação e expiração. Ideal para softwares, plugins e CLIs.

Digital Files

Entregue arquivos para download (e-books, templates, mídias) com URLs de download pré-assinadas e instruções opcionais.

Discord

Conceda a um cliente um papel no seu servidor Discord quando ele comprar. Revogue automaticamente no cancelamento.

GitHub

Adicione clientes como colaboradores a um repositório privado no nível de permissão que você escolher.

Telegram

Adicione clientes a um chat ou canal privado no Telegram após a compra.

Framer

Desbloqueie um link de remix de template Framer para clientes pagantes.

Notion

Duplique um template do Notion no espaço de trabalho do cliente na compra.

​
Como as Grants Funcionam

As grants são impulsionadas pelos mesmos eventos de pagamento e assinatura que você já recebe como webhooks. Você não precisa chamar a API de grant para cada compra. O Dodo Payments cria e revoga grants automaticamente com base no ciclo de pagamento subjacente.

​
Ciclo de Vida da Grant

1

Created

Uma grant é criada quando um pagamento é concluído ou uma assinatura se torna ativa. Chaves de licença vão direto para delivered. Todas as outras integrações começam em pending. Integrações baseadas em OAuth (Discord, GitHub, Notion) incluem um oauth_url que o cliente deve visitar para completar o consentimento. Integrações diretas de plataforma (Telegram, Framer, Arquivos Digitais) permanecem em pending apenas brevemente enquanto a entrega é provisionada, então transitam para delivered.
2

Delivered

Uma vez que a entrega é concluída (chave de licença gerada, papel atribuído, acesso ao repositório concedido, links de arquivos resolvidos, OAuth concluído), a grant se move para delivered e delivered_at é definido.
3

Failed

Se a chamada de integração retornar um erro não-retryable (token OAuth revogado, permissão negada, arquivo não existe mais), a grant se move para failed. Os campos error_code e error_message capturam o motivo.
4

Revoked

Quando o acesso é retirado (assinatura cancelada, reembolso emitido ou revogação iniciada pelo comerciante), a grant se move para revoked. O campo revocation_reason registra o gatilho.

​
Comportamento da Grant por Evento

EventoComportamento
payment.succeeded (pagamento único)Emita uma grant por entitlement anexado.
payment.succeeded (pagamento vinculado à assinatura)Sem ação. Grants são impulsionadas pelo evento de assinatura abaixo.
subscription.activeEmita grants para quaisquer entitlements anexados que ainda não tenham uma. Re-grante quaisquer grants previamente revogadas para a mesma assinatura.
subscription.renewedSem ação. Grants existentes persistem em renovações.
subscription.on_holdRevogue todas as grants entregues e pendentes. revocation_reason: subscription_on_hold.
subscription.cancelledRevogue tudo. revocation_reason: subscription_cancelled.
subscription.expiredRevogue tudo. revocation_reason: subscription_expired.
subscription.plan_changedRevogue todas as grants atuais, então emita grants para os entitlements do novo plano. revocation_reason: plan_changed.
refund.succeeded (pagamento único)Revogue grants para esse pagamento. revocation_reason: refund.
Revogação manual de APIRevogue com revocation_reason: manual. Revogações manuais não são automaticamente re-grantadas na renovação da assinatura.
Chave de licença desativadaPara grants de chave de licença, desativar a chave subjacente revoga a grant com revocation_reason: license_key_disabled. A grant é reativada automaticamente se a chave for reativada.
Desvio de plataforma detectadoSe o lado da plataforma de uma integração sair de sincronia (um papel no Discord removido manualmente, o App do GitHub perdendo acesso ao repositório ou um passe de reconciliação detectando um alvo ausente), a grant é revogada com revocation_reason: platform_external. Não é automaticamente re-grantada na renovação da assinatura até que o problema subjacente da plataforma seja resolvido.
Grants impulsionadas por assinaturas são idempotentes por (entitlement, customer, subscription); renovações e reativações não criam grants duplicadas. Grants de uma única vez são idempotentes por (entitlement, customer, payment).

​
Crie seu primeiro entitlement

1

Open Entitlements

Vá para Entitlements no seu painel do Dodo Payments e clique em + para criar um novo entitlement.
2

Pick an integration

Escolha o tipo de integração: Chave de Licença, Arquivos Digitais, Discord, GitHub, Telegram, Framer ou Notion. Para integrações de plataforma, conecte sua conta primeiro, se ainda não tiver feito isso.
3

Configure delivery

Preencha os campos específicos da integração. Por exemplo, GitHub pede um repositório e um nível de permissão; Discord pede um servidor e um papel opcional; Chave de Licença pede limites de ativação e expiração.
Formulário de Novo Entitlement com seletor de integração e campos de configuração
4

Save

Salve o entitlement. Você agora pode anexá-lo a qualquer produto.

​
Anexe Entitlements a Produtos

Abra um produto, expanda Configurações Avançadas → Entitlements & Créditos, e selecione os entitlements que devem ser entregues quando o produto for comprado. Um único produto pode entregar múltiplos entitlements de uma vez. Por exemplo, um plano Pro pode incluir uma chave de licença, acesso ao GitHub e um papel no Discord.
Painel de seleção de entitlements de produto mostrando caixas de seleção para cada entitlement disponível

​
Experiência do Cliente

​
E-mail e portal do cliente

Os clientes recebem um e-mail de entrega após a compra contendo a chave de licença, links para download, links de convite OAuth ou convite para plataforma, conforme aplicável aos entitlements do produto. Os mesmos detalhes permanecem disponíveis indefinidamente no Portal do Cliente sob o histórico de pedidos.

​
Entrega baseada em OAuth

O acesso ao Discord, GitHub e Notion para assinantes exige que o cliente autorize o Dodo Payments a conceder acesso a eles. Essas grants permanecem em status pending até que o cliente complete o fluxo OAuth usando o link do e-mail ou do portal do cliente. Uma vez que autorizam, a grant se move para delivered e o acesso à plataforma é provisionado imediatamente.

​
Revogação

Grants revogados são removidos no nível da plataforma: o papel do Discord é removido, o colaborador do GitHub é removido, a chave de licença é desativada. Os clientes veem a mudança refletida no portal do cliente.
Para Arquivos Digitais, a revogação remove o acesso às URLs pré-assinadas a partir de então, mas não invalida cópias que o cliente já baixou. Planeje o conteúdo do plano de acordo.

​
Gerenciar Grants

Abra qualquer entitlement no painel para ver suas grants. O painel de detalhes da grant mostra o total de grants, filtros de status, informações do cliente, datas de entrega e uma ação de revogação. Você também pode gerenciar grants programaticamente: 
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', {
  path_id: 'ent_abc123',
});

​
Gerenciamento via API

Create Entitlement

Crie um novo entitlement de qualquer tipo de integração.

List Entitlements

Liste entitlements com filtro por tipo de integração.

Get Entitlement

Recupere um entitlement e sua configuração resolvida.

Update Entitlement

Atualize o nome, descrição ou configuração de integração.

Delete Entitlement

Exclua um entitlement suavemente; grants existentes não são afetadas.

Upload File

Carregue um arquivo para um entitlement de Arquivos Digitais (até 100 MB).

List Grants

Liste todas as grants de um entitlement com filtros de status e cliente.

Revoke Grant

Revogue manualmente uma única grant.

​
Webhooks

O Dodo Payments dispara quatro eventos de webhook para o ciclo de vida da grant. Assine esses eventos para manter seu aplicativo em sincronia com o que cada cliente pode acessar.
EventoDispara quando
entitlement_grant.createdUma nova grant é criada. Grants de chave de licença chegam delivered; toda outra integração chega pending e transita para delivered uma vez que a chamada à plataforma seja bem-sucedida (ou, para integrações baseadas em OAuth, uma vez que o cliente autorize).
entitlement_grant.deliveredA grant transita para entregue. O cliente agora tem acesso.
entitlement_grant.failedA grant não pôde ser entregue. Inspecione error_code e error_message.
entitlement_grant.revokedO acesso foi retirado. Inspecione revocation_reason.

Entitlement Grant Webhook Payloads

Veja o esquema completo de payload, eventos de exemplo e referência revocation_reason.

​
Melhores Práticas

  • Use um entitlement por canal de entrega. Não compartilhe um único entitlement do Discord por produtos com diferentes intenções de papel; crie um por papel para uma revogação limpa.
  • Teste primeiro no modo de teste. Crie o entitlement, anexe-o a um produto de teste, realize um checkout e veja a grant transitar por pending → delivered. Confirme que o cancelamento da assinatura de teste revoga a grant.
  • Ouça entitlement_grant.delivered, não payment.succeeded. Um pagamento pode ter sucesso antes de o fulfillment terminar (especialmente para fluxos OAuth). Aguarde o evento entregue antes de desbloquear recursos dependentes em seus próprios sistemas.
  • Considere entitlement_grant.failed como acionável. Uma grant falhada significa que um cliente pagou mas não obteve acesso. Exiba isso para sua equipe de suporte ou ative um regrant.
  • Mapeie revocation_reason para seus fluxos de retenção. Uma revogação subscription_on_hold é recuperável (o cliente pode atualizar seu cartão). Uma revogação manual é intencional. Trate-os de forma diferente nas comunicações com clientes.
Last modified on May 14, 2026