Feature Flag Entitlement

​

Cosa viene consegnato

• Al momento dell’acquisto, il diritto viene creato e passa direttamente a delivered. Non c’è nessuna fase pending, nessuna azione del cliente e nessun modo per il fallimento della consegna.
• Il diritto porta un payload tipizzato feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. La tua applicazione legge feature_id per decidere cosa sbloccare.
• Cancellazione, rimborso o revoca manuale sposta il diritto a revoked, e la tua applicazione vede il flag scomparire.

​

Crea un feature flag

1

Open Entitlements

Nel tuo dashboard di Dodo Payments, vai a Entitlements e clicca + per iniziare un nuovo entitlement, quindi scegli Feature Flags.

2

Name the flag

Dai al flag un Display Name per il tuo dashboard, un Feature ID che la tua applicazione verificherà (il dashboard suggerisce uno dal nome), e una Description per far sapere al tuo team cosa controlla.

3

Optionally add metadata

Attiva Meta Data per allegare configurazioni chiave-valore — limiti, nomi di livelli, quote — che vengono consegnati alla tua applicazione insieme al flag. Vedi Allega limiti con metadati.

4

Confirm

Clicca Conferma. Il flag appare nella tua lista di entitlements, pronto per essere associato ai prodotti.

​

Associa a un prodotto

​

Configurazione richiesta

​

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

​

Allega limiti con metadati

• Modificare i metadati dell’entitlement in un secondo momento influisce solo sui futuri diritti. I clienti mantengono i limiti sotto i quali hanno acquistato.
• L’istantanea viene restituita su ogni diritto come suo campo metadata, quindi una chiamata API ti dà sia il flag che la sua configurazione.

​

Verifica le funzionalità di 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 di vita

​

Webhooks

• entitlement_grant.created — arriva già delivered con il payload feature. Abilita la funzionalità.
• entitlement_grant.delivered — si attiva quando un diritto precedentemente revocato viene ripristinato. Riabilita la funzionalità.
• entitlement_grant.revoked — accesso ritirato. Disabilita la funzionalità e controlla revocation_reason per decidere il tuo messaggio.

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

​

Esempio: Il piano Pro sblocca i report avanzati

1. Crea il flag. feature_id: advanced_reports con metadati { "tier": "pro", "monthly_report_limit": 100 }.
2. Associalo al prodotto di abbonamento del tuo Pro Plan.
3. Un cliente si abbona. Dodo Payments crea un diritto delivered e genera entitlement_grant.created; il tuo gestore webhook abilita advanced_reports per il cliente con un limite di 100.
4. La tua app attiva la funzione. Al caricamento del dashboard, controlla l’insieme delle funzionalità memorizzato nella cache (o chiama listEntitlementGrants) e visualizza la scheda dei report solo quando advanced_reports è presente.
5. Il cliente cancella. Dodo Payments revoca il diritto e genera entitlement_grant.revoked; il tuo gestore disabilita la funzione. Se il cliente in seguito si riprende tramite riscossione, entitlement_grant.delivered la ripristina — nessuna modifica al codice necessaria.

​

Migliori pratiche

• Usa ID funzionalità stabili in snake_case. Il codice della tua applicazione controlla queste stringhe; rinominare uno è un cambiamento radicale su entrambi i lati.
• Un flag per capacità. Preferisci advanced_reports + api_access come due entitlements su un singolo pro_bundle — revoca e combinazioni di piani rimangono pulite.
• Guida lo stato dai webhooks, verifica con l’API. I webhooks mantengono il tuo database aggiornato; l’endpoint della lista è la fonte della verità per i lavori di riconciliazione e gli eventi cache miss.
• Tratta revoked come immediato. Un flag revocato significa che il cliente non sta più pagando per la funzionalità. Attivalo alla prossima richiesta, non alla prossima sessione.
• Metti i limiti nei metadati, non nel codice. Cambiare una quota richiede solo di modificare la entitlement — i nuovi clienti la acquisiscono automaticamente mentre i diritti esistenti mantengono la loro istantanea acquistata.

​

Best practices

• Use stable, snake_case feature ids. Your application code checks these strings; renaming one is a breaking change on both sides.
• One flag per capability. Prefer advanced_reports + api_access as two entitlements over a single pro_bundle — revocation and plan mixes stay clean.
• Drive state from webhooks, verify with the API. Webhooks keep your database current; the list endpoint is the source of truth for reconciliation jobs and cache misses.
• Treat revoked as immediate. A revoked flag means the customer is no longer paying for the feature. Gate on the next request, not the next session.
• Put limits in metadata, not in code. Changing a quota then only requires editing the entitlement — new customers pick it up automatically while existing grants keep their purchased snapshot.