Feature Flag Entitlement

एक feature flag entitlement Dodo Payments को billing-aware feature-flag store में बदल देता है। किसी product से advanced_reports जैसा flag attach करें, और प्रत्येक paying customer को एक grant मिलता है जिसे आपका application API के माध्यम से check कर सकता है या webhooks के साथ sync में रख सकता है। किसी external platform, OAuth या delivery step की आवश्यकता नहीं है — grant स्वयं capability है।

क्या deliver होता है

Dodo Payments से कुछ भी बाहर नहीं जाता — grant ही deliverable है:

खरीदारी पर grant बनाया जाता है और सीधे Delivered पर चला जाता है। कोई Pending चरण नहीं होता, customer की ओर से कोई कार्रवाई नहीं करनी पड़ती और delivery के विफल होने की कोई संभावना नहीं होती।
grant में typed feature payload होता है: { "feature_type": "boolean", "feature_id": "advanced_reports" }। क्या unlock करना है, यह तय करने के लिए आपका application feature_id पढ़ता है।
Cancellation, refund या manual revoke grant को Revoked पर ले जाता है और आपका application flag के हटने को देखता है।

सामान्य उपयोगों में plan-based feature gating (Pro से analytics unlock करना), add-on capabilities (“API access” upgrade) और one-time purchases के रूप में बेचे जाने वाले early-access programs शामिल हैं।

feature_id merchant द्वारा चुना गया identifier है और entitlements में unique नहीं होता। दो entitlements एक ही feature_id प्रदान कर सकते हैं — उदाहरण के लिए, monthly और yearly Pro plan दोनों advanced_reports प्रदान कर सकते हैं।

Feature flag बनाएं

Open Entitlements

अपने Dodo Payments dashboard में Entitlements पर जाएं और नया entitlement शुरू करने के लिए + पर click करें, फिर Feature Flags चुनें।

Name the flag

अपने dashboard के लिए flag को Display Name, application द्वारा check किया जाने वाला Feature ID (dashboard name से एक ID सुझाता है) और एक Description दें, ताकि आपकी team को पता रहे कि यह किसे नियंत्रित करता है।

New Feature Flag form with display name, feature ID, description, and metadata key-value entries — Creating a feature flag. The Feature ID is what your application checks; Meta Data attaches limits alongside the flag.

Optionally add metadata

Flag के साथ key-value configuration — limits, tier names, quotas — attach करने के लिए Meta Data toggle करें। यह configuration flag के साथ आपके application तक deliver की जाती है। Attach limits with metadata देखें।

Confirm

Confirm पर click करें। Flag आपकी entitlements list में दिखाई देगा और products से attach करने के लिए तैयार होगा।

Entitlements dashboard showing the Advanced Reports feature flag with its grant activity pane — The created feature flag. The right pane tracks every customer grant issued from it.

Product से attach करें

किसी product को खोलें (या नया बनाएं), Entitlements card खोजें और मौजूदा entitlements attach करने के लिए + पर click करें। अपना feature flag चुनें और Done पर click करें।

Entitlements attach panel with the Advanced Reports feature flag selected — Attaching the feature flag to a product. One product can deliver multiple entitlements.

Attached flag product form पर दिखाई देता है और checkout preview इसे Includes के अंतर्गत सूचीबद्ध करता है।

Product form with the Advanced Reports feature flag attached in the Entitlements card — The product now includes the feature flag. Every successful purchase or active subscription grants it.

आवश्यक configuration

Field	Required	Description
`feature_id`	Yes	वह identifier जिसे आपका application check करता है, जैसे `advanced_reports`। Entitlements में unique नहीं होता।
`feature_type`	Yes	प्रदान की गई capability का type। आज केवल `boolean` supported है।

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

Metadata के साथ limits attach करें

Boolean flag इस प्रश्न का उत्तर देता है: “क्या इस customer के पास feature है?” Metadata बताता है: “किस configuration के साथ?” Entitlement metadata string, integer, number और boolean values स्वीकार करता है, और प्रत्येक grant बनने के समय entitlement के metadata का एक frozen snapshot लेता है। यही snapshot behavior metadata को plan limits के लिए सुरक्षित बनाता है:

बाद में entitlement का metadata edit करने पर केवल future grants प्रभावित होते हैं। Customers अपने खरीदे गए limits के अनुसार बने रहते हैं।
Snapshot प्रत्येक grant पर उसके metadata field के रूप में लौटाया जाता है, इसलिए एक API call से flag और उसकी configuration दोनों मिलती हैं।

उदाहरण के लिए, advanced_reports flag के साथ { "tier": "pro", "monthly_report_limit": 100 } होने पर आपका application dashboard unlock करने के साथ 100-report quota भी enforce कर सकता है, बिना किसी दूसरे lookup के। यदि बाद में limit को 250 कर दिया जाए, तो मौजूदा customers 100 पर ही रहेंगे, जब तक उन्हें नया grant न मिले (उदाहरण के लिए, plan change के बाद)।

Limits और configuration के लिए metadata का उपयोग करें; identity के लिए केवल feature_id का उपयोग करें। ID में limits encode करना (advanced_reports_100) प्रत्येक limit change के लिए नया flag बनाने को मजबूर करता है और आपके application के checks को तोड़ देता है।

Customer के features check करें

Customer के delivered feature-flag grants की list बनाएं और enabled features का set तैयार करें। Endpoint सभी entitlements में प्रत्येक grant के लिए एक row लौटाता है, जिसे integration_type और status से filter किया जा सकता है।

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

feature payload केवल feature_flag grants पर populated होता है; हर दूसरे integration type के लिए यह null होता है। पूर्ण response shape के लिए List Customer Grants API reference देखें।

हर request पर API check करने से आपके hot path में latency बढ़ती है। प्रत्येक customer के लिए feature set को short TTL (hours नहीं, minutes) के साथ cache करें और grant की state बदलने पर अपने webhook handler से cache invalidate करें — यह संयोजन checks को fast और revocations को लगभग instant रखता है।

Lifecycle

Feature flag grants standard grant lifecycle का पालन करते हैं, जिसमें एक सरलीकरण है: delivery step नहीं होता, इसलिए grants कभी भी Pending में नहीं रहते और न ही Failed पर जाते हैं।

Trigger	प्रभाव
One-time payment सफल होता है / subscription active हो जाती है	`status: delivered` और `delivered_at` सेट के साथ grant बनाया जाता है।
Subscription को hold पर रखा जाता है, cancel किया जाता है या उसकी अवधि समाप्त हो जाती है	संबंधित `revocation_reason` के साथ grant revoke किया जाता है।
One-time payment पर refund	`revocation_reason: refund` के साथ grant revoke किया जाता है।
Subscription recover होती है (उदाहरण के लिए, dunning सफल होता है)	Revoked grant को `Delivered` पर restore किया जाता है — वही grant `id`, revocation fields clear किए जाते हैं।
Manual API revoke	`revocation_reason: manual` के साथ grant revoke किया जाता है। Renewal पर auto-restore नहीं होता।

Grants प्रत्येक entitlement और customer के लिए idempotent होते हैं: जब तक customer के पास किसी flag का non-revoked grant है, repeat purchases और renewals duplicates नहीं बनाते।

Webhooks

Polling के बजाय flags को अपने database में mirror करने के लिए entitlement_grant.* events को subscribe करें:

entitlement_grant.created — यह पहले से ही Delivered और feature payload के साथ आता है। Feature enable करें।
entitlement_grant.delivered — पहले revoked grant के restore होने पर fire होता है। Feature फिर से enable करें।
entitlement_grant.revoked — access वापस ले लिया गया है। Feature disable करें और अपने messaging का निर्णय लेने के लिए revocation_reason जाँचें।

TypeScript

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

Feature flags के लिए कोई entitlement_grant.failed नहीं है — delivery पूरी तरह Dodo Payments के भीतर होती है और fail नहीं हो सकती।

उदाहरण: Pro plan से advanced reports unlock करना

Flag बनाएँ। feature_id: advanced_reports को metadata { "tier": "pro", "monthly_report_limit": 100 } के साथ बनाएँ।
इसे attach करें अपने Pro Plan subscription product से।
Customer subscription लेता है। Dodo Payments एक Delivered grant बनाता है और entitlement_grant.created fire करता है; आपका webhook handler customer के लिए advanced_reports को 100 की limit के साथ enable करता है।
आपका app feature को gate करता है। Dashboard load होने पर cached feature set जाँचें (या listEntitlementGrants call करें) और reports tab को तभी render करें जब advanced_reports मौजूद हो।
Customer cancel करता है। Dodo Payments grant revoke करता है और entitlement_grant.revoked fire करता है; आपका handler feature disable करता है। यदि customer बाद में dunning के माध्यम से recover करता है, तो entitlement_grant.delivered इसे restore कर देता है — code में किसी बदलाव की आवश्यकता नहीं।

Best practices

Stable, snake_case feature ids का उपयोग करें। आपका application code इन strings की जाँच करता है; किसी id का नाम बदलना दोनों पक्षों पर breaking change है।
प्रत्येक capability के लिए एक flag रखें। एकल pro_bundle के बजाय advanced_reports + api_access को दो entitlements के रूप में प्राथमिकता दें — revocation और plan mixes व्यवस्थित रहते हैं।
State को webhooks से संचालित करें और API से verify करें। Webhooks आपके database को current रखते हैं; list endpoint reconciliation jobs और cache misses के लिए source of truth है।
Revoked को immediate मानें। Revoked flag का अर्थ है कि customer अब feature के लिए भुगतान नहीं कर रहा है। अगली session पर नहीं, बल्कि अगली request पर gate करें।
Limits को code में नहीं, metadata में रखें। Quota बदलने के लिए केवल entitlement को edit करना पड़ेगा — नए customers इसे automatically अपना लेंगे, जबकि existing grants अपने purchased snapshot को बनाए रखेंगे।

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

क्या deliver होता है

Feature flag बनाएं

Product से attach करें

आवश्यक configuration

API के माध्यम से बनाएं

Metadata के साथ limits attach करें

Customer के features check करें

Lifecycle

Webhooks

उदाहरण: Pro plan से advanced reports unlock करना

Best practices

​क्या deliver होता है

​Feature flag बनाएं

​Product से attach करें

​आवश्यक configuration

​API के माध्यम से बनाएं

​Metadata के साथ limits attach करें

​Customer के features check करें

​Lifecycle

​Webhooks

​उदाहरण: Pro plan से advanced reports unlock करना

​Best practices

क्या deliver होता है

Feature flag बनाएं

Product से attach करें

आवश्यक configuration

API के माध्यम से बनाएं

Metadata के साथ limits attach करें

Customer के features check करें

Lifecycle

Webhooks

उदाहरण: Pro plan से advanced reports unlock करना

Best practices