Feature Flag Entitlement

​

What Gets Delivered

• On purchase, Dodo Payments creates the grant directly in Delivered. It never enters Pending, needs no customer action, and has no delivery step that can fail.
• The grant carries a typed feature payload: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Your application reads feature_id to decide what to unlock.
• Cancellation, refund, or a manual revoke moves the grant to Revoked, and the flag disappears from the customer’s delivered grants.

​

Create a Feature Flag

1

Open Entitlements

In the Dodo Payments dashboard, go to Entitlements and click + to start a new entitlement, then choose Feature Flags.

2

Name the Flag

Enter a Display Name for your dashboard and reports, and a Description so your team knows what the flag controls. The Feature ID is what your application checks. The dashboard fills it in from the display name (for example, “API access” becomes api_access), and you can edit it. It can’t contain spaces.

3

Add Metadata (Optional)

Turn on Meta Data to attach key-value configuration, such as limits, tier names, or quotas, that your application receives alongside the flag. Click Add Entry for each pair. See Attach limits with metadata.

4

Confirm

Click Confirm. The flag appears in your entitlements list, ready to attach to products.

​

Attach to a Product

​

Required Configuration

​

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

​

Attach Limits with Metadata

• Editing the entitlement’s metadata later affects only future grants. Customers keep the limits they purchased under.
• Each grant returns its snapshot in its metadata field, so one API call gives you both the flag and its configuration.

​

Check a Customer’s Features

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

​

Lifecycle

​

Webhooks

• entitlement_grant.created arrives already Delivered, with the feature payload. Enable the feature.
• entitlement_grant.delivered fires when a previously revoked grant is restored. Enable the feature again.
• entitlement_grant.revoked means access was withdrawn. Disable the feature, and check revocation_reason to choose your messaging.

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

​

Example: Pro Plan Unlocks Advanced Reports

1. Create the flag. Set feature_id: advanced_reports with metadata { "tier": "pro", "monthly_report_limit": 100 }.
2. Attach it to your Pro Plan subscription product.
3. A customer subscribes. Dodo Payments creates a Delivered grant and fires entitlement_grant.created. Your webhook handler enables advanced_reports for the customer with a limit of 100.
4. Your app gates the feature. On dashboard load, check the cached feature set (or call listEntitlementGrants) and render the reports tab only when advanced_reports is present.
5. The customer cancels. Dodo Payments revokes the grant and fires entitlement_grant.revoked, and your handler disables the feature. If a subscription later recovers through dunning, entitlement_grant.delivered restores the feature with no code changes.

​

Best Practices

• Use stable feature IDs in snake_case. Your application code checks these strings, so renaming one is a breaking change on both sides.
• Use one flag per capability. Prefer advanced_reports and api_access as two entitlements over a single pro_bundle, so revocation and plan combinations stay clean.
• Drive state from webhooks, and 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 no longer pays for the feature. Gate on the next request, not the next session.
• Put limits in metadata, not in code. Changing a quota then requires only an edit to the entitlement. New customers get the new value, and existing grants keep their purchased snapshot.