Introdução

Entregue automaticamente chaves de licença, arquivos para download e acesso a plataformas como Discord, GitHub, Telegram, Framer e Notion quando os clientes pagam.

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.

The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.

​

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

Evento	Comportamento
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.active	Emita grants para quaisquer entitlements anexados que ainda não tenham uma. Re-grante quaisquer grants previamente revogadas para a mesma assinatura.
subscription.renewed	Sem ação. Grants existentes persistem em renovações.
subscription.on_hold	Revogue todas as grants entregues e pendentes. revocation_reason: subscription_on_hold.
subscription.cancelled	Revogue tudo. revocation_reason: subscription_cancelled.
subscription.expired	Revogue tudo. revocation_reason: subscription_expired.
subscription.plan_changed	Revogue 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 API	Revogue com revocation_reason: manual. Revogações manuais não são automaticamente re-grantadas na renovação da assinatura.
Chave de licença desativada	Para 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 detectado	Se 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.

   

   Creating a GitHub entitlement. Each integration shows the fields it needs.

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.

Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.

---

​

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:

TypeScript

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',
});

client.entitlements.grants.list(
    "ent_abc123",
    status="delivered",
)

client.entitlements.grants.revoke(
    "grant_xyz789",
    path_id="ent_abc123",
)

grants, _ := client.Entitlements.Grants.List(
  ctx, "ent_abc123",
  dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)

_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "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.

Evento	Dispara quando
entitlement_grant.created	Uma 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.delivered	A grant transita para entregue. O cliente agora tem acesso.
entitlement_grant.failed	A grant não pôde ser entregue. Inspecione error_code e error_message.
entitlement_grant.revoked	O 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.