Entitlement de Feature Flag

​

O que é entregue

• Na compra, o Dodo Payments cria a concessão diretamente em Delivered. Ela nunca entra em Pending, não exige nenhuma ação do cliente e não tem uma etapa de entrega que possa falhar.
• A concessão contém um payload feature tipado: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Sua aplicação lê feature_id para decidir o que desbloquear.
• Cancelamento, reembolso ou uma revogação manual move a concessão para Revoked, e a flag desaparece das concessões entregues ao cliente.

​

Criar uma feature flag

1

Open Entitlements

No dashboard do Dodo Payments, acesse Entitlements e clique em + para iniciar uma nova concessão; depois, escolha Feature Flags.

2

Name the Flag

Insira um Display Name para o dashboard e os relatórios e uma Description para que sua equipe saiba o que a flag controla. O Feature ID é o que sua aplicação verifica. O dashboard o preenche com base no nome de exibição (por exemplo, “API access” se torna api_access), e você pode editá-lo. Ele não pode conter espaços.

3

Add Metadata (Optional)

Ative Meta Data para anexar uma configuração de chave-valor, como limites, nomes de níveis ou cotas, que sua aplicação recebe junto com a flag. Clique em Add Entry para cada par. Consulte 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,
  },
});

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

entitlement = 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 is a *dodopayments.Client, for example from
// dodopayments.NewClient(option.WithEnvironmentTestMode()); ctx is a context.Context.
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 da concessão posteriormente afeta apenas concessões futuras. Os clientes mantêm os limites sob os quais compraram.
• Cada concessão retorna seu snapshot no campo metadata, portanto uma chamada à API fornece a flag e sua configuração.

​

Verificar os 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",
)

# Iterating the page fetches every page of results.
features = {
    grant.feature.feature_id: grant.metadata
    for grant in page
    if grant.feature
}

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

iter := client.Customers.ListEntitlementGrantsAutoPaging(
  ctx, "cus_abc123",
  dodopayments.CustomerListEntitlementGrantsParams{
    IntegrationType: dodopayments.F(dodopayments.CustomerListEntitlementGrantsParamsIntegrationTypeFeatureFlag),
    Status:          dodopayments.F(dodopayments.CustomerListEntitlementGrantsParamsStatusDelivered),
  },
)

features := map[string]bool{}
for iter.Next() {
  grant := iter.Current()
  if grant.Feature.FeatureID != "" {
    features[grant.Feature.FeatureID] = true
  }
}
if err := iter.Err(); err != nil {
  panic(err.Error())
}

​

Ciclo de vida

​

Webhooks

• entitlement_grant.created chega já em Delivered, com o payload feature. Habilite o recurso.
• entitlement_grant.delivered é disparado quando uma concessão anteriormente revogada é restaurada. Habilite o recurso novamente.
• entitlement_grant.revoked significa que o acesso foi retirado. Desabilite o recurso e verifique revocation_reason para escolher sua mensagem.

import express from 'express';
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_WEBHOOK_KEY from the environment.
const client = new DodoPayments({ environment: 'test_mode' });
const app = express();

app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: DodoPayments.UnwrapWebhookEvent;
  try {
    event = client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers as Record<string, string>,
    });
  } catch {
    res.sendStatus(400); // invalid signature
    return;
  }

  const grant = 'feature' in event.data ? event.data : null;

  if (event.type.startsWith('entitlement_grant.') && grant?.feature) {
    const enabled = event.type !== 'entitlement_grant.revoked';

    // db is your application's database client.
    await db.customerFeatures.upsert({
      customerId: grant.customer_id,
      featureId: grant.feature.feature_id,
      enabled,
      config: grant.metadata ?? {},
    });
  }

  res.sendStatus(200);
});

​

Exemplo: o plano Pro desbloqueia relatórios avançados

1. Crie a flag. Defina feature_id: advanced_reports com os metadados { "tier": "pro", "monthly_report_limit": 100 }.
2. Anexe-a ao produto de assinatura do seu plano Pro.
3. Um cliente assina. O Dodo Payments cria uma concessão Delivered e dispara entitlement_grant.created. Seu handler de webhook habilita advanced_reports para o cliente com um limite de 100.
4. Sua aplicação controla o acesso ao recurso. Ao carregar o dashboard, verifique o conjunto de recursos armazenado em cache (ou chame listEntitlementGrants) e renderize a aba de relatórios somente quando advanced_reports estiver presente.
5. O cliente cancela. O Dodo Payments revoga a concessão e dispara entitlement_grant.revoked, e seu handler desabilita o recurso. Se uma assinatura se recuperar posteriormente por meio de dunning, entitlement_grant.delivered restaura o recurso sem alterações no código.

​

Boas práticas

• Use IDs de recursos estáveis em snake_case. O código da sua aplicação verifica essas strings, portanto renomear uma delas é uma alteração incompatível nos dois lados.
• Use uma flag por capacidade. Prefira advanced_reports e api_access como duas concessões, em vez de uma única pro_bundle, para manter organizadas a revogação e as combinações de planos.
• Baseie o estado em webhooks e verifique com a API. Os 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 paga mais pelo recurso. Controle o acesso na próxima solicitação, não na próxima sessão.
• Coloque os limites nos metadados, não no código. Alterar uma cota exige apenas editar a concessão. Novos clientes recebem o novo valor, e as concessões existentes mantêm o snapshot que foi comprado.