Derecho de Bandera de Función

​

Qué se entrega

• En la compra, se crea la concesión y pasa directamente a delivered. No hay fase de pending, no hay acción del cliente, y no hay forma de que la entrega falle.
• La concesión lleva una carga útil tipificada feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Tu aplicación lee feature_id para decidir qué desbloquear.
• La cancelación, reembolso o revocación manual mueven la concesión a revoked, y tu aplicación ve desaparecer la bandera.

​

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 delivered con la carga útil feature. Activa la función.
• entitlement_grant.delivered — se activa cuando una concesión previamente revocada se restaura. Re-activa la función.
• entitlement_grant.revoked — acceso retirado. Desactiva la función y verifica revocation_reason para decidir tu mensajería.

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 la bandera. feature_id: advanced_reports con metadatos { "tier": "pro", "monthly_report_limit": 100 }.
2. Adjúntala a tu producto de suscripción del Plan Pro.
3. Un cliente se suscribe. Dodo Payments crea una concesión delivered y dispara entitlement_grant.created; tu manejador de webhooks habilita advanced_reports para el cliente con un límite de 100.
4. Tu aplicación restringe la función. Al cargar el panel, verifica el conjunto de características en caché (o llama listEntitlementGrants) y renderiza la pestaña de informes solo cuando advanced_reports está presente.
5. El cliente cancela. Dodo Payments revoca la concesión y dispara entitlement_grant.revoked; tu manejador desactiva la función. Si el cliente luego se recupera a través de cobro, entitlement_grant.delivered la restaura — no se necesitan cambios de código.

​

Mejores prácticas

• Usa ids de función estables y en snake_case. Tu código de aplicación verifica estas cadenas; renombrar una es un cambio de ruptura en ambos lados.
• Una bandera por capacidad. Prefiere advanced_reports + api_access como dos derechos sobre un solo pro_bundle — la revocación y las mezclas de plan se mantienen limpias.
• Impulsa el estado desde webhooks, verifica con la API. Los webhooks mantienen tu base de datos actualizada; el punto de lista es la fuente de verdad para trabajos de reconciliación y pérdidas de caché.
• Trata revoked como inmediato. Una bandera revocada significa que el cliente ya no está pagando por la función. Verifica en la siguiente solicitud, no en la siguiente sesión.
• Pon límites en metadatos, no en el código. Cambiar una cuota luego solo requiere editar el derecho — los nuevos clientes la adoptan automáticamente mientras que las concesiones existentes mantienen su instantánea comprada.