Droits de Fonctions de Fonctionnalité

​

Ce qui est livré

• Lors de l’achat, le grant est créé et passe directement à Delivered. Il n’y a aucune phase Pending, aucune action du client et aucun risque d’échec de la livraison.
• Le grant contient un payload feature typé : { "feature_type": "boolean", "feature_id": "advanced_reports" }. Votre application lit feature_id pour déterminer ce qu’il faut débloquer.
• Une annulation, un remboursement ou une révocation manuelle fait passer le grant à Revoked, et votre application constate la disparition du flag.

​

Créer une fonction de fonctionnalité

1

Open Entitlements

Dans votre tableau de bord Dodo Payments, allez à Droits et cliquez sur + pour commencer un nouveau droit, puis choisissez Fonctions de Fonctionnalité.

2

Name the flag

Donnez à la fonction un Nom d’Affichage pour votre tableau de bord, un ID de Fonctionnalité que votre application vérifiera (le tableau de bord en suggère un à partir du nom), et une Description pour que votre équipe sache ce qu’elle contrôle.

3

Optionally add metadata

Basculez Meta Data pour attacher une configuration clé-valeur — limites, noms de niveaux, quotas — qui est livrée à votre application en même temps que la fonction. Voir Attacher des limites avec des métadonnées.

4

Confirm

Cliquez sur Confirmer. La fonction apparaît dans votre liste de droits, prête à attacher à des produits.

​

Attacher à un produit

​

Configuration requise

​

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

​

Attacher des limites avec des métadonnées

• Modifier ultérieurement les métadonnées du droit n’affecte que les futures concessions. Les clients conservent les limites avec lesquelles ils ont acheté.
• L’instantané est renvoyé sur chaque concession sous son champ metadata, donc un appel API vous donne à la fois la fonction et sa configuration.

​

Vérifier les fonctionnalités d’un client

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

​

Cycle de vie

​

Webhooks

• entitlement_grant.created — arrive déjà à Delivered avec le payload feature. Activez la fonctionnalité.
• entitlement_grant.delivered — se déclenche lorsqu’un grant précédemment révoqué est restauré. Réactivez la fonctionnalité.
• entitlement_grant.revoked — accès retiré. Désactivez la fonctionnalité et vérifiez revocation_reason pour déterminer le message à afficher.

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

​

Exemple : Pro plan débloque les rapports avancés

1. Créez le flag. feature_id: advanced_reports avec les métadonnées { "tier": "pro", "monthly_report_limit": 100 }.
2. Associez-le au produit d’abonnement Pro Plan.
3. Un client s’abonne. Dodo Payments crée un grant Delivered et déclenche entitlement_grant.created ; votre gestionnaire de webhook active advanced_reports pour le client avec une limite de 100.
4. Votre application contrôle l’accès à la fonctionnalité. Lors du chargement du dashboard, vérifiez l’ensemble de fonctionnalités mis en cache (ou appelez listEntitlementGrants) et affichez l’onglet des rapports uniquement lorsque advanced_reports est présent.
5. Le client annule son abonnement. Dodo Payments révoque le grant et déclenche entitlement_grant.revoked ; votre gestionnaire désactive la fonctionnalité. Si le client rétablit ensuite son abonnement grâce au recouvrement, entitlement_grant.delivered la restaure — aucune modification du code n’est nécessaire.

​

Meilleures pratiques

• Utilisez des identifiants de feature stables en snake_case. Le code de votre application vérifie ces chaînes ; renommer l’une d’elles constitue une modification incompatible des deux côtés.
• Un flag par capacité. Préférez advanced_reports + api_access comme deux entitlements plutôt qu’un seul pro_bundle — les révocations et les combinaisons de plans restent ainsi propres.
• Faites évoluer l’état à partir des webhooks et vérifiez-le avec l’API. Les webhooks maintiennent votre base de données à jour ; l’endpoint de liste est la source de vérité pour les tâches de réconciliation et les absences du cache.
• Traitez Revoked comme immédiat. Un flag révoqué signifie que le client ne paie plus pour la fonctionnalité. Contrôlez l’accès à la prochaine requête, pas à la prochaine session.
• Placez les limites dans les métadonnées, pas dans le code. Modifier un quota nécessite alors uniquement de modifier l’entitlement — les nouveaux clients l’utilisent automatiquement, tandis que les grants existants conservent leur snapshot acheté.