Feature Flag Entitlement

​

Cosa viene consegnato

• Al momento dell’acquisto, il grant viene creato e passa direttamente a Delivered. Non esiste alcuna fase Pending, non è richiesta alcuna azione da parte del cliente e non è possibile che la delivery non vada a buon fine.
• Il grant contiene un payload feature tipizzato: { "feature_type": "boolean", "feature_id": "advanced_reports" }. La tua applicazione legge feature_id per decidere cosa sbloccare.
• L’annullamento, il rimborso o la revoca manuale spostano il grant a Revoked e la tua applicazione rileva la scomparsa del flag.

​

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

• entitlement_grant.created — arriva già in stato Delivered con il payload feature. Abilita la funzionalità.
• entitlement_grant.delivered — viene attivato quando un grant precedentemente revocato viene ripristinato. Riabilita la funzionalità.
• entitlement_grant.revoked — accesso revocato. Disabilita la funzionalità e controlla revocation_reason per decidere quale messaggio mostrare.

​

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.

1. Crea il flag. feature_id: advanced_reports con i metadati { "tier": "pro", "monthly_report_limit": 100 }.
2. Assoc ialo al prodotto di abbonamento Pro Plan.
3. Un cliente sottoscrive l’abbonamento. Dodo Payments crea un grant Delivered e attiva entitlement_grant.created; il tuo gestore webhook abilita advanced_reports per il cliente con un limite di 100.
4. La tua app controlla l’accesso alla funzionalità. Al caricamento della dashboard, controlla il set di funzionalità memorizzato nella cache (oppure chiama listEntitlementGrants) e visualizza la scheda dei report solo quando advanced_reports è presente.
5. Il cliente annulla l’abbonamento. Dodo Payments revoca il grant e attiva entitlement_grant.revoked; il tuo gestore disabilita la funzionalità. Se in seguito il cliente recupera i pagamenti, entitlement_grant.delivered la ripristina — non sono necessarie modifiche al codice.

• 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

• Usa ID di funzionalità stabili in snake_case. Il codice della tua applicazione controlla queste stringhe; rinominarne una è una modifica incompatibile su entrambi i lati.
• Un flag per ogni funzionalità. Preferisci advanced_reports + api_access come due entitlement invece di un singolo pro_bundle: la revoca e le combinazioni di piani restano più semplici da gestire.
• Gestisci lo stato tramite webhook e verifica tramite API. I webhook mantengono aggiornato il database; l’endpoint di elenco è la fonte autorevole per i processi di riconciliazione e le cache miss.
• Tratta Revoked come immediato. Un flag revocato significa che il cliente non sta più pagando per la funzionalità. Applica il controllo alla richiesta successiva, non alla sessione successiva.
• Inserisci i limiti nei metadati, non nel codice. Per modificare una quota è quindi sufficiente aggiornare l’entitlement: i nuovi clienti la ricevono automaticamente, mentre i grant esistenti mantengono lo snapshot acquistato.