Derecho de Bandera de Función

​

Qué se entrega

• Al realizar la compra, se crea el grant y pasa directamente a Delivered. No existe una fase Pending, no se requiere ninguna acción del cliente y no hay forma de que la entrega falle.
• El grant contiene un payload feature tipado: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Tu aplicación lee feature_id para decidir qué desbloquear.
• Una cancelación, un reembolso o una revocación manual mueve el grant a Revoked, y tu aplicación ve desaparecer el indicador.

​

Crear una bandera de función

1

Open Entitlements

En tu panel de Dodo Payments, ve a Derechos y haz clic en + para iniciar un nuevo derecho, luego elige Banderas de Función.

2

Name the flag

Dale a la bandera un Nombre de Presentación para tu panel, un ID de Función que verificará tu aplicación (el panel sugiere uno a partir del nombre), y una Descripción para que tu equipo sepa qué controla.

3

Optionally add metadata

Activa Metadatos para adjuntar configuración clave-valor — límites, nombres de niveles, cuotas — que se entrega a tu aplicación junto con la bandera. Consulta Adjuntar límites con metadatos.

4

Confirm

Haz clic en Confirmar. La bandera aparece en tu lista de derechos, lista para adjuntar a productos.

​

Adjuntar a un producto

​

Configuración requerida

​

Crear vía 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"),
    },
  ),
})

​

Adjuntar límites con metadatos

• Editar los metadatos del derecho más tarde solo afecta a las futuras concesiones. Los clientes mantienen los límites bajo los que compraron.
• La instantánea se devuelve en cada concesión como su campo metadata, por lo que una llamada API te da tanto la bandera como su configuración.

​

Comprobar las características de un 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 — llega ya en Delivered con el payload feature. Activa la funcionalidad.
• entitlement_grant.delivered — se dispara cuando se restaura un grant revocado anteriormente. Vuelve a activar la funcionalidad.
• entitlement_grant.revoked — se retira el acceso. Desactiva la funcionalidad y comprueba revocation_reason para decidir qué mensaje mostrar.

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

​

Ejemplo: El plan Pro desbloquea informes avanzados

1. Crea el indicador. feature_id: advanced_reports con los metadatos { "tier": "pro", "monthly_report_limit": 100 }.
2. Asócialo al producto de suscripción Pro Plan.
3. Un cliente se suscribe. Dodo Payments crea un grant Delivered y dispara entitlement_grant.created; tu webhook habilita advanced_reports para el cliente con un límite de 100.
4. Tu aplicación controla el acceso a la funcionalidad. Al cargar el dashboard, comprueba el conjunto de funcionalidades almacenado en caché (o llama a listEntitlementGrants) y muestra la pestaña de informes solo cuando advanced_reports esté presente.
5. El cliente cancela. Dodo Payments revoca el grant y dispara entitlement_grant.revoked; tu webhook desactiva la funcionalidad. Si el cliente se recupera posteriormente mediante el proceso de cobro de deuda, entitlement_grant.delivered la restaura; no se necesitan cambios de código.

​

Mejores prácticas

• Usa ids de feature estables en snake_case. El código de tu aplicación comprueba estas cadenas; cambiarles el nombre es un cambio incompatible en ambos lados.
• Un indicador por capacidad. Es preferible advanced_reports + api_access como dos entitlements en lugar de un único pro_bundle: la revocación y las combinaciones de planes se mantienen ordenadas.
• Obtén el estado de los webhooks y verifícalo con la API. Los webhooks mantienen actualizada tu base de datos; el endpoint de lista es la fuente de verdad para los procesos de reconciliación y las ausencias de caché.
• Trata Revoked como inmediato. Un indicador revocado significa que el cliente ya no está pagando por la funcionalidad. Controla el acceso en la siguiente solicitud, no en la siguiente sesión.
• Coloca los límites en los metadatos, no en el código. Cambiar una cuota solo requiere editar el entitlement; los nuevos clientes la obtienen automáticamente, mientras que los grants existentes conservan la configuración adquirida.