Entitlement de Feature Flag

​

O que é entregue

• Na compra, o grant é criado e passa diretamente para Delivered. Não há uma fase Pending, nenhuma ação do cliente e nenhuma possibilidade de falha na entrega.
• O grant contém um payload tipado feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Sua aplicação lê feature_id para decidir o que desbloquear.
• O cancelamento, reembolso ou revogação manual move o grant 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 — já chega em Delivered com o payload feature. Ative a feature.
• entitlement_grant.delivered — é acionado quando um grant anteriormente revogado é restaurado. Reative a feature.
• entitlement_grant.revoked — acesso retirado. Desative a feature 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 os metadados { "tier": "pro", "monthly_report_limit": 100 }.
2. Associe-a ao produto de assinatura Pro Plan.
3. Um cliente assina. Dodo Payments cria um grant Delivered e aciona entitlement_grant.created; seu webhook handler ativa advanced_reports para o cliente com um limite de 100.
4. Seu app controla o acesso à feature. Ao carregar o dashboard, verifique o conjunto de features em cache (ou chame listEntitlementGrants) e renderize a aba de relatórios somente quando advanced_reports estiver presente.
5. O cliente cancela. Dodo Payments revoga o grant e aciona entitlement_grant.revoked; seu handler desativa a feature. Se o cliente se recuperar posteriormente por meio de dunning, entitlement_grant.delivered a restaura — nenhuma alteração de código é necessária.

​

Melhores práticas

• Use IDs de feature estáveis em snake_case. O código da sua aplicação verifica essas strings; renomear uma delas é uma alteração incompatível em ambos os lados.
• Uma flag por capacidade. Prefira advanced_reports + api_access como dois entitlements em vez de um único pro_bundle — a revogação e as combinações de planos permanecem organizadas.
• Use webhooks para controlar o estado e verifique com a API. Webhooks mantêm seu banco de dados atualizado; o endpoint de listagem é a fonte de verdade para jobs de reconciliação e falhas de cache.
• Trate Revoked como imediato. Uma flag revogada significa que o cliente não está mais pagando pela feature. Controle o acesso na próxima requisição, não na próxima sessão.
• Coloque os limites nos metadados, não no código. Alterar uma quota exige apenas editar o entitlement — novos clientes a recebem automaticamente, enquanto os grants existentes mantêm o snapshot adquirido.