Derecho de Bandera de Función

Una concesión de feature flag convierte Dodo Payments en un almacén de feature flags consciente de la facturación. Asocie un flag como advanced_reports a un producto y cada cliente que pague recibirá una concesión que su aplicación comprobará mediante la API o mantendrá sincronizada con webhooks. No hay ninguna plataforma externa, paso de OAuth ni paso de entrega: la propia concesión es la capacidad.

Qué se entrega

Nada sale de Dodo Payments. La concesión es el elemento entregable:

Tras la compra, Dodo Payments crea la concesión directamente en Delivered. Nunca entra en Pending, no requiere ninguna acción del cliente y no tiene ningún paso de entrega que pueda fallar.
La concesión incluye un payload tipado de feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Su aplicación lee feature_id para decidir qué desbloquear.
La cancelación, el reembolso o una revocación manual mueve la concesión a Revoked, y el flag desaparece de las concesiones entregadas al cliente.

Usos comunes incluyen la restricción de funciones basadas en planes (Pro desbloquea analíticas), capacidades adicionales (una mejora de “acceso API”), y programas de acceso temprano vendidos como compras únicas.

feature_id es un identificador que usted elige y no es único entre las concesiones. Dos concesiones pueden otorgar el mismo feature_id; por ejemplo, un plan Pro mensual y uno anual que otorguen ambos advanced_reports.

Crear un feature flag

Open Entitlements

En el dashboard de Dodo Payments, vaya a Entitlements y haga clic en + para iniciar una nueva concesión; después, seleccione Feature Flags.

Name the Flag

Introduzca un Display Name para el dashboard y los informes, y una Description para que su equipo sepa qué controla el flag. El Feature ID es lo que comprueba su aplicación. El dashboard lo completa a partir del nombre visible (por ejemplo, “API access” se convierte en api_access), y puede editarlo. No puede contener espacios.

Formulario de Nueva Bandera de Función con nombre de presentación, ID de función, descripción y entradas de metadatos clave-valor — Creating a feature flag. The Feature ID is what your application checks; Meta Data attaches limits alongside the flag.

Add Metadata (Optional)

Active Meta Data para asociar una configuración de clave-valor, como límites, nombres de niveles o cuotas, que su aplicación recibirá junto con el flag. Haga clic en Add Entry para cada par. Consulte Asociar límites con metadatos.

Confirm

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

Panel de derechos mostrando la bandera de función de Informes Avanzados con su panel de actividad de concesión — The created feature flag. The right pane tracks every customer grant issued from it.

Asociar a un producto

Abra un producto o cree uno y busque la tarjeta Entitlements. Haga clic en + para asociar concesiones existentes, seleccione su feature flag y haga clic en Done.

Panel de adjuntos de derechos con la bandera de función de Informes Avanzados seleccionada — Attaching the feature flag to a product. One product can deliver multiple entitlements.

La bandera adjunta se muestra en el formulario del producto, y la vista previa del pago la lista bajo Incluye.

Formulario de producto con la bandera de función de Informes Avanzados adjunta en la tarjeta de Derechos — The product now includes the feature flag. Every successful purchase or active subscription grants it.

Configuración necesaria

Campo	Obligatorio	Descripción
`feature_id`	Sí	El identificador que comprueba su aplicación, por ejemplo `advanced_reports`. No es único entre las concesiones.
`feature_type`	Sí	El tipo de capacidad otorgada. `boolean` es el único valor compatible.

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

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"),
    },
  ),
})

Asociar límites con metadatos

Un flag booleano responde a «¿Tiene este cliente la función?». Los metadatos responden a «¿Con qué configuración?». Los metadatos de la concesión aceptan valores de tipo string, integer, number y boolean. Cada concesión toma una instantánea inmutable de los metadatos de la concesión cuando se crea. La instantánea es lo que hace que los metadatos sean seguros para usar con límites de planes:

Editar posteriormente los metadatos de la concesión solo afecta a las concesiones futuras. Los clientes conservan los límites con los que realizaron la compra.
Cada concesión devuelve su instantánea en el campo metadata, por lo que una sola llamada a la API le proporciona tanto el flag como su configuración.

Por ejemplo, un flag advanced_reports con { "tier": "pro", "monthly_report_limit": 100 } permite que su aplicación desbloquee el dashboard y además aplique la cuota de 100 informes sin una segunda consulta. Si posteriormente aumenta el límite a 250, los clientes existentes permanecerán en 100 hasta que reciban una nueva concesión, por ejemplo, después de cambiar de plan.

Use los metadatos para los límites y la configuración, y use feature_id únicamente para la identidad. Codificar un límite en el ID (advanced_reports_100) obliga a crear un nuevo flag para cada cambio de límite y rompe las comprobaciones de su aplicación.

Comprobar las funciones de un cliente

Para crear el conjunto de funciones que tiene un cliente, enumere sus concesiones de feature flags entregadas. El endpoint devuelve una fila por concesión en todas las concesiones y puede filtrarlo por integration_type y status. Estos ejemplos usan el client de Crear mediante la API.

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

El payload de feature solo se completa en las concesiones de feature_flag. Es null para cualquier otro tipo de integración. Consulte la referencia de API List Customer Grants para conocer la estructura completa de la respuesta.

Llamar a la API en cada solicitud añade latencia a su ruta crítica. Almacene en caché el conjunto de funciones de cada cliente con un TTL corto (minutos, no horas) e invalide la caché desde su controlador de webhook cuando cambie el estado de una concesión. En conjunto, esto mantiene rápidas las comprobaciones y hace que las revocaciones surtan efecto en la siguiente solicitud.

Ciclo de vida

Las concesiones de feature flags siguen el ciclo de vida de las concesiones estándar, con una simplificación: no hay ningún paso de entrega, por lo que las concesiones nunca permanecen en Pending ni pasan a Failed.

Activador	Efecto
El pago único se completa / la suscripción pasa a estar activa	Se crea la concesión con `status: Delivered` y `delivered_at` establecidos.
La suscripción se pone en espera, se pausa, se cancela o caduca	Se revoca la concesión con el `revocation_reason` correspondiente.
Reembolso de un pago único	Se revoca la concesión con `revocation_reason: refund`.
La suscripción se recupera (por ejemplo, se completa el proceso de cobro) o se reanuda	La concesión revocada se restaura a `Delivered`, con el mismo `id` de concesión y los campos de revocación eliminados.
Revocación manual mediante la API	Se revoca la concesión con `revocation_reason: manual`. No se restaura automáticamente al renovar.

Las concesiones son idempotentes por concesión y cliente. Mientras un cliente tenga una concesión no revocada para un flag, las compras repetidas y las renovaciones no crean duplicados.

Webhooks

Para replicar los flags en su propia base de datos en lugar de hacer polling, suscríbase a los eventos de entitlement_grant.*:

entitlement_grant.created llega ya en estado Delivered, con el payload de feature. Active la función.
entitlement_grant.delivered se activa cuando se restaura una concesión previamente revocada. Vuelva a activar la función.
entitlement_grant.revoked indica que se retiró el acceso. Desactive la función y compruebe revocation_reason para elegir el mensaje que mostrará.

Este controlador de Express verifica la firma del webhook con el SDK y, a continuación, almacena el estado del flag:

TypeScript

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

Los feature flags nunca activan entitlement_grant.failed, porque la entrega se realiza completamente dentro de Dodo Payments.

Ejemplo: el plan Pro desbloquea informes avanzados

Cree el flag. Establezca feature_id: advanced_reports con los metadatos { "tier": "pro", "monthly_report_limit": 100 }.
Asócielo al producto de suscripción del plan Pro.
Un cliente se suscribe. Dodo Payments crea una concesión Delivered y activa entitlement_grant.created. Su controlador de webhook activa advanced_reports para el cliente con un límite de 100.
Su aplicación controla la función. Al cargar el dashboard, compruebe el conjunto de funciones almacenado en caché (o llame a listEntitlementGrants) y muestre la pestaña de informes solo cuando esté presente advanced_reports.
El cliente cancela. Dodo Payments revoca la concesión y activa entitlement_grant.revoked, y su controlador desactiva la función. Si posteriormente la suscripción se recupera mediante el proceso de cobro, entitlement_grant.delivered restaura la función sin cambios en el código.

Prácticas recomendadas

Use IDs de feature estables en snake_case. El código de su aplicación comprueba estas cadenas, por lo que cambiar el nombre de una es un cambio incompatible en ambos lados.
Use un flag por capacidad. Es preferible usar advanced_reports y api_access como dos concesiones en lugar de un único pro_bundle, para que las revocaciones y las combinaciones de planes se mantengan claras.
Gestione el estado mediante webhooks y verifíquelo con la API. Los webhooks mantienen actualizada su base de datos. El endpoint de listado es la fuente de verdad para los trabajos de conciliación y los fallos de caché.
Trate Revoked como inmediato. Un flag revocado significa que el cliente ya no paga por la función. Controle el acceso en la siguiente solicitud, no en la siguiente sesión.
Coloque los límites en los metadatos, no en el código. Cambiar una cuota requerirá entonces únicamente editar la concesión. Los nuevos clientes obtendrán el nuevo valor y las concesiones existentes conservarán la instantánea adquirida.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Qué se entrega

Crear un feature flag

Asociar a un producto

Configuración necesaria

Crear vía API

Asociar límites con metadatos

Comprobar las funciones de un cliente

Ciclo de vida

Webhooks

Ejemplo: el plan Pro desbloquea informes avanzados

Prácticas recomendadas

​Qué se entrega

​Crear un feature flag

​Asociar a un producto

​Configuración necesaria

​Crear vía API

​Asociar límites con metadatos

​Comprobar las funciones de un cliente

​Ciclo de vida

​Webhooks

​Ejemplo: el plan Pro desbloquea informes avanzados

​Prácticas recomendadas

Qué se entrega

Crear un feature flag

Asociar a un producto

Configuración necesaria

Crear vía API

Asociar límites con metadatos

Comprobar las funciones de un cliente

Ciclo de vida

Webhooks

Ejemplo: el plan Pro desbloquea informes avanzados

Prácticas recomendadas