Entitlement de Feature Flag

​

O que é entregue

• Na compra, a concessão é criada e move-se diretamente para delivered. Não há fase pending, nenhuma ação do cliente, e nenhuma possibilidade de falha na entrega.
• A concessão carrega um payload digitado feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Sua aplicação lê feature_id para decidir o que desbloquear.
• Cancelamento, reembolso, ou revogação manual movem a concessão para revoked, e sua aplicação vê a flag desaparecer.

​

Criar uma feature flag

1

Open Entitlements

No seu painel do Dodo Payments, vá para Entitlements e clique em + para iniciar um novo entitlement, depois escolha Feature Flags.

2

Name the flag

Dê à flag um Nome de Exibição para seu painel, um ID de Recurso que sua aplicação irá verificar (o painel sugere um a partir do nome), e uma Descrição para que sua equipe saiba o que controla.

3

Optionally add metadata

Alternar Meta Data para anexar configuração chave-valor — limites, nomes de níveis, cotas — que é entregue à sua aplicação junto com a flag. Veja Anexar limites com metadados.

4

Confirm

Clique em Confirmar. A flag aparece na sua lista de entitlements, pronta para ser anexada aos produtos.

​

Anexar a um produto

​

Configuração obrigatória

​

Criar via API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode',
});

const entitlement = await client.entitlements.create({
  name: 'Advanced Reports',
  integration_type: 'feature_flag',
  integration_config: {
    feature_type: 'boolean',
    feature_id: 'advanced_reports',
  },
  metadata: {
    tier: 'pro',
    monthly_report_limit: 100,
  },
});

client.entitlements.create(
    name="Advanced Reports",
    integration_type="feature_flag",
    integration_config={
        "feature_type": "boolean",
        "feature_id": "advanced_reports",
    },
    metadata={
        "tier": "pro",
        "monthly_report_limit": 100,
    },
)

client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
  Name:            dodopayments.F("Advanced Reports"),
  IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeFeatureFlag),
  IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
    dodopayments.IntegrationConfigFeatureFlagConfigParam{
      FeatureType: dodopayments.F(dodopayments.FeatureTypeBoolean),
      FeatureID:   dodopayments.F("advanced_reports"),
    },
  ),
})

​

Anexar limites com metadados

• Editar os metadados do entitlement posteriormente afeta apenas as concessões futuras. Os clientes mantêm os limites sob os quais foram comprados.
• O instantâneo é retornado em cada concessão como seu campo metadata, então uma chamada API fornece tanto a flag quanto sua configuração.

​

Verificar recursos de um cliente

const features = new Map<string, Record<string, unknown>>();

for await (const grant of client.customers.listEntitlementGrants('cus_abc123', {
  integration_type: 'feature_flag',
  status: 'Delivered',
})) {
  if (grant.feature) {
    features.set(grant.feature.feature_id, grant.metadata ?? {});
  }
}

if (features.has('advanced_reports')) {
  const limit = features.get('advanced_reports')?.monthly_report_limit;
  // unlock the dashboard, enforce the limit
}

page = client.customers.list_entitlement_grants(
    customer_id="cus_abc123",
    integration_type="feature_flag",
    status="Delivered",
)

features = {
    grant.feature.feature_id: grant.metadata
    for grant in page.items
    if grant.feature
}

if "advanced_reports" in features:
    limit = features["advanced_reports"].get("monthly_report_limit")

page, _ := client.Customers.ListEntitlementGrants(
  ctx, "cus_abc123",
  dodopayments.CustomerListEntitlementGrantsParams{
    IntegrationType: dodopayments.F("feature_flag"),
    Status:          dodopayments.F("Delivered"),
  },
)

features := map[string]bool{}
for _, grant := range page.Items {
  if grant.Feature.FeatureID != "" {
    features[grant.Feature.FeatureID] = true
  }
}

​

Ciclo de vida

​

Webhooks

• entitlement_grant.created — chega já delivered com o payload feature. Habilite o recurso.
• entitlement_grant.delivered — dispara quando uma concessão anteriormente revogada é restaurada. Re-habilite o recurso.
• entitlement_grant.revoked — acesso retirado. Desabilite o recurso e verifique revocation_reason para decidir sua mensagem.

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  if (event.type.startsWith('entitlement_grant.') && event.data.feature) {
    const { customer_id, feature } = event.data;
    const enabled = event.type !== 'entitlement_grant.revoked';

    await db.customerFeatures.upsert({
      customerId: customer_id,
      featureId: feature.feature_id,
      enabled,
      config: event.data.metadata ?? {},
    });
  }

  res.sendStatus(200);
});

​

Exemplo: Plano Pro desbloqueia relatórios avançados

1. Crie a flag. feature_id: advanced_reports com metadados { "tier": "pro", "monthly_report_limit": 100 }.
2. Anexe-a ao seu produto de assinatura Pro Plan.
3. Um cliente se inscreve. O Dodo Payments cria uma concessão delivered e dispara entitlement_grant.created; seu manipulador de webhook habilita advanced_reports para o cliente com um limite de 100.
4. Sua aplicação bloqueia o recurso. Ao carregar o dashboard, verifique o conjunto de funcionalidades em cache (ou chame listEntitlementGrants) e exiba a aba de relatórios apenas quando advanced_reports estiver presente.
5. O cliente cancela. O Dodo Payments revoga a concessão e dispara entitlement_grant.revoked; seu manipulador desabilita o recurso. Se o cliente se recuperar posteriormente por meio de dunning, entitlement_grant.delivered o restaura — nenhuma alteração de código necessária.

​

Melhores práticas

• Use ids de recursos estáveis e em snake_case. O código da sua aplicação verifica essas strings; renomear uma é uma mudança quebradora em ambos os lados.
• Uma flag por capacidade. Prefira advanced_reports + api_access como dois entitlements ao invés de um único pro_bundle — a revogação e as misturas de planos permanecem limpas.
• Dirija o estado a partir de webhooks, verifique com a API. Webhooks mantêm seu banco de dados atualizado; o endpoint de lista é a fonte de verdade para trabalhos de reconciliação e falhas de cache.
• Trate revoked como imediato. Uma flag revogada significa que o cliente não está mais pagando pelo recurso. Bloqueie na próxima solicitação, não na próxima sessão.
• Coloque limites em metadados, não em código. Alterar uma cota só requer editar o entitlement — novos clientes a capturam automaticamente enquanto concessões existentes mantêm seu instantâneo comprado.