Feature Flag Entitlement

​

What gets delivered

• On purchase, the grant is created and moves straight to delivered. There is no pending phase, no customer action, and no way for delivery to 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 manual revoke moves the grant to revoked, and your application sees the flag disappear.

​

Create a feature flag

1

Open Entitlements

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

2

Name the flag

Give the flag a Display Name for your dashboard, a Feature ID your application will check (the dashboard suggests one from the name), and a Description so your team knows what it controls.

3

Optionally add metadata

Toggle Meta Data to attach key-value configuration — limits, tier names, quotas — that is delivered to your application alongside the flag. 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,
  },
});

​

Attach limits with metadata

• Editing the entitlement’s metadata later only affects future grants. Customers keep the limits they purchased under.
• The snapshot is returned on each grant as 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
}

​

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. Re-enable the feature.
• entitlement_grant.revoked — access withdrawn. Disable the feature and check revocation_reason to decide your messaging.

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

​

Example: Pro plan unlocks advanced reports

1. Create the flag. 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; your handler disables the feature. If the customer later recovers via dunning, entitlement_grant.delivered restores it — no code changes needed.

​

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.