Droits de Fonctions de Fonctionnalité

Un droit de feature flag transforme Dodo Payments en plateforme de feature flags consciente de la facturation. Associez un flag tel que advanced_reports à un produit, et chaque client payant reçoit un grant que votre application vérifie via l’API ou synchronise avec les webhooks. Aucune plateforme externe, étape OAuth ou étape de livraison n’est nécessaire : le grant lui-même constitue la capacité.

Ce qui est fourni

Rien ne sort de Dodo Payments. Le grant est le livrable :

Lors de l’achat, Dodo Payments crée directement le grant dans Delivered. Il n’entre jamais dans Pending, ne nécessite aucune action du client et ne comporte aucune étape de livraison susceptible d’échouer.
Le grant contient un payload feature typé : { "feature_type": "boolean", "feature_id": "advanced_reports" }. Votre application lit feature_id pour décider quoi déverrouiller.
Une annulation, un remboursement ou une révocation manuelle fait passer le grant à Revoked, et le flag disparaît des grants fournis au client.

Les utilisations courantes incluent la gestion des fonctionnalités basées sur des plans (Pro débloque les analyses), les capacités supplémentaires (une mise à niveau “accès API”), et les programmes d’accès anticipé vendus sous forme d’achats uniques.

feature_id est un identifiant que vous choisissez et qui n’est pas unique parmi les droits. Deux droits peuvent conférer le même feature_id, par exemple un forfait Pro mensuel et annuel qui accordent tous deux advanced_reports.

Créer un feature flag

Open Entitlements

Dans le tableau de bord Dodo Payments, accédez à Entitlements et cliquez sur + pour commencer un nouveau droit, puis choisissez Feature Flags.

Name the Flag

Saisissez un Display Name pour votre tableau de bord et vos rapports, ainsi qu’une Description afin que votre équipe sache ce que contrôle le flag. Le Feature ID est la valeur vérifiée par votre application. Le tableau de bord le renseigne à partir du nom d’affichage (par exemple, « API access » devient api_access), et vous pouvez le modifier. Il ne peut pas contenir d’espaces.

Formulaire de nouvelle fonction de fonctionnalité avec nom d'affichage, ID de fonctionnalité, description et entrées de métadonnées — Creating a feature flag. The Feature ID is what your application checks; Meta Data attaches limits alongside the flag.

Add Metadata (Optional)

Activez Meta Data pour associer une configuration clé-valeur, comme des limites, des noms de niveaux ou des quotas, que votre application reçoit avec le flag. Cliquez sur Add Entry pour chaque paire. Consultez Associer des limites avec des métadonnées.

Confirm

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

Tableau de bord des droits avec la fonction de fonctionnalité Rapports Avancés et son panneau d'activité de concession — The created feature flag. The right pane tracks every customer grant issued from it.

Associer à un produit

Ouvrez un produit ou créez-en un, puis recherchez la carte Entitlements. Cliquez sur + pour associer des droits existants, sélectionnez votre feature flag et cliquez sur Done.

Panneau d'attachement des droits avec la fonction de fonctionnalité Rapports Avancés sélectionnée — Attaching the feature flag to a product. One product can deliver multiple entitlements.

La fonction attachée s’affiche sur le formulaire de produit, et la prévisualisation du paiement la répertorie sous Comprend.

Formulaire de produit avec la fonction de fonctionnalité Rapports Avancés attachée dans la carte Droits — The product now includes the feature flag. Every successful purchase or active subscription grants it.

Configuration requise

Champ	Requis	Description
`feature_id`	Oui	L’identifiant vérifié par votre application, par exemple `advanced_reports`. Non unique parmi les droits.
`feature_type`	Oui	Le type de capacité conférée. `boolean` est la seule valeur prise en charge.

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

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

Associer des limites avec des métadonnées

Un flag booléen répond à la question « Ce client dispose-t-il de cette fonctionnalité ? ». Les métadonnées répondent à la question « Avec quelle configuration ? ». Les métadonnées des droits acceptent les valeurs de type chaîne, entier, nombre et booléen. Chaque grant prend un instantané figé des métadonnées du droit lors de sa création. L’instantané rend les métadonnées sûres pour gérer les limites des forfaits :

Modifier ultérieurement les métadonnées du droit n’affecte que les grants futurs. Les clients conservent les limites correspondant à leur achat.
Chaque grant renvoie son instantané dans son champ metadata, de sorte qu’un seul appel API vous fournit à la fois le flag et sa configuration.

Par exemple, un flag advanced_reports avec { "tier": "pro", "monthly_report_limit": 100 } permet à votre application de déverrouiller le tableau de bord et d’appliquer le quota de 100 rapports sans seconde recherche. Si vous augmentez ensuite la limite à 250, les clients existants restent à 100 jusqu’à ce qu’ils reçoivent un nouveau grant, par exemple après un changement de forfait.

Utilisez les métadonnées pour les limites et la configuration, et utilisez feature_id uniquement pour l’identité. Encoder une limite dans l’ID (advanced_reports_100) impose de créer un nouveau flag à chaque modification de limite et interrompt les vérifications de votre application.

Vérifier les fonctionnalités d’un client

Pour constituer l’ensemble des fonctionnalités dont dispose un client, listez ses grants de feature flags fournis. L’endpoint renvoie une ligne par grant pour l’ensemble des droits, et vous pouvez le filtrer par integration_type et status. Ces exemples utilisent client de Créer via l’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())
}

Le payload feature est renseigné uniquement pour les grants feature_flag. Il vaut null pour tous les autres types d’intégration. Consultez la référence API List Customer Grants pour connaître la structure complète de la réponse.

Appeler l’API à chaque requête ajoute de la latence à votre chemin critique. Mettez en cache l’ensemble des fonctionnalités de chaque client avec un TTL court (quelques minutes, et non plusieurs heures), puis invalidez le cache depuis votre gestionnaire de webhook lorsqu’un grant change d’état. Ensemble, ces mesures accélèrent les vérifications et rendent les révocations effectives dès la requête suivante.

Cycle de vie

Les grants de feature flags suivent le cycle de vie standard d’un grant, avec une simplification : il n’y a pas d’étape de livraison. Les grants ne restent donc jamais dans Pending et ne passent jamais à Failed.

Déclencheur	Effet
Le paiement ponctuel réussit / l’abonnement devient actif	Grant créé avec `status: Delivered` et `delivered_at` définis.
L’abonnement est suspendu, mis en pause, annulé ou expire	Grant révoqué avec le `revocation_reason` correspondant.
Remboursement d’un paiement ponctuel	Grant révoqué avec `revocation_reason: refund`.
L’abonnement est rétabli (par exemple, le recouvrement aboutit) ou sort de pause	Le grant révoqué est restauré à `Delivered`, avec le même `id` de grant et les champs de révocation effacés.
Révocation manuelle via l’API	Grant révoqué avec `revocation_reason: manual`. Restauré automatiquement lors du renouvellement.

Les grants sont idempotents par droit et par client. Tant qu’un client dispose d’un grant non révoqué pour un flag, les achats répétés et les renouvellements ne créent pas de doublons.

Webhooks

Pour répliquer les flags dans votre propre base de données plutôt que d’effectuer des interrogations périodiques, abonnez-vous aux événements entitlement_grant.* :

entitlement_grant.created arrive déjà Delivered, avec le payload feature. Activez la fonctionnalité.
entitlement_grant.delivered est déclenché lorsqu’un grant précédemment révoqué est restauré. Activez à nouveau la fonctionnalité.
entitlement_grant.revoked signifie que l’accès a été retiré. Désactivez la fonctionnalité et vérifiez revocation_reason pour choisir votre message.

Ce gestionnaire Express vérifie la signature du webhook avec le SDK, puis enregistre l’état du 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);
});

Les feature flags ne déclenchent jamais entitlement_grant.failed, car la livraison s’effectue entièrement dans Dodo Payments.

Exemple : le forfait Pro déverrouille les rapports avancés

Créez le flag. Définissez feature_id: advanced_reports avec les métadonnées { "tier": "pro", "monthly_report_limit": 100 }.
Associez-le à votre produit d’abonnement Pro Plan.
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.
Votre application contrôle l’accès à la fonctionnalité. Lors du chargement du tableau de bord, vérifiez l’ensemble des fonctionnalités mis en cache (ou appelez listEntitlementGrants) et affichez l’onglet des rapports uniquement lorsque advanced_reports est présent.
Le client annule. Dodo Payments révoque le grant et déclenche entitlement_grant.revoked ; votre gestionnaire désactive alors la fonctionnalité. Si un abonnement est ensuite rétabli grâce au recouvrement, entitlement_grant.delivered restaure la fonctionnalité sans modification du code.

Bonnes pratiques

Utilisez des Feature IDs stables dans snake_case. Le code de votre application vérifie ces chaînes ; en renommer une constitue donc une modification incompatible des deux côtés.
Utilisez un flag par capacité. Préférez advanced_reports et api_access comme deux droits plutôt qu’un seul pro_bundle, afin que les révocations et les combinaisons de forfaits restent simples.
Pilotez l’état depuis les 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 rapprochement 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 dès la requête suivante, et non à la session suivante.
Placez les limites dans les métadonnées, pas dans le code. Pour modifier un quota, il suffit alors de modifier le droit. Les nouveaux clients obtiennent la nouvelle valeur et les grants existants conservent l’instantané acheté.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Ce qui est fourni

Créer un feature flag

Associer à un produit

Configuration requise

Créer via API

Associer des limites avec des métadonnées

Vérifier les fonctionnalités d’un client

Cycle de vie

Webhooks

Exemple : le forfait Pro déverrouille les rapports avancés

Bonnes pratiques

​Ce qui est fourni

​Créer un feature flag

​Associer à un produit

​Configuration requise

​Créer via API

​Associer des limites avec des métadonnées

​Vérifier les fonctionnalités d’un client

​Cycle de vie

​Webhooks

​Exemple : le forfait Pro déverrouille les rapports avancés

​Bonnes pratiques

Ce qui est fourni

Créer un feature flag

Associer à un produit

Configuration requise

Créer via API

Associer des limites avec des métadonnées

Vérifier les fonctionnalités d’un client

Cycle de vie

Webhooks

Exemple : le forfait Pro déverrouille les rapports avancés

Bonnes pratiques