> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Feature-Flag-Berechtigung
> Funktionen in Ihrer Anwendung hinter einem Kauf abschalten. Feature-Flag-Berechtigungen liefern eine sofortige boolesche Fähigkeit bei Zahlung und widerrufen sie automatisch bei Stornierung.
Eine Feature-Flag-Berechtigung verwandelt Dodo Payments in einen abrechnungsbewussten Feature-Flag-Speicher. Hängen Sie ein Flag wie `advanced_reports` an ein Produkt, und jeder zahlende Kunde erhält eine Berechtigung, die Ihre Anwendung über API überprüfen oder mit Webhooks synchron halten kann. Keine externe Plattform, kein OAuth, kein Lieferstep — die Berechtigung selbst ist die Fähigkeit.
## Was geliefert wird
Nichts verlässt Dodo Payments — die Berechtigung **ist** das Lieferbare:
* Beim Kauf wird die Berechtigung erstellt und direkt zu `delivered` verschoben. Es gibt keine `pending`-Phase, keine Kundenaktion und keine Möglichkeit für ein Lieferversagen.
* Die Berechtigung trägt eine typisierte `feature`-Nutzlast: `{ "feature_type": "boolean", "feature_id": "advanced_reports" }`. Ihre Anwendung liest `feature_id`, um zu entscheiden, was freigeschaltet wird.
* Stornierungen, Rückerstattungen oder manuelle Widerrufe verschieben die Berechtigung zu `revoked`, und Ihre Anwendung sieht das Flag verschwinden.
Häufige Anwendungsfälle umfassen planbasierte Feature-Gatings (Pro schaltet Analysen frei), Zusatzfähigkeiten (ein "API-Zugriff"-Upgrade) und Early-Access-Programme, die als Einmalkäufe verkauft werden.
`feature_id` ist eine vom Händler gewählte Kennung, die nicht einzigartig für Berechtigungen ist. Zwei Berechtigungen können die gleiche `feature_id` verleihen — zum Beispiel, ein monatlicher und ein jährlicher Pro-Plan, die beide `advanced_reports` gewähren.
## Erstellen eines Feature-Flags
Gehen Sie in Ihrem Dodo Payments-Dashboard zu **Berechtigungen** und klicken Sie auf **+**, um eine neue Berechtigung zu starten, und wählen Sie dann **Feature Flags**.
Geben Sie dem Flag einen **Anzeigenamen** für Ihr Dashboard, eine **Feature-ID**, die Ihre Anwendung überprüfen wird (das Dashboard schlägt eine basierend auf dem Namen vor), und eine **Beschreibung**, damit Ihr Team weiß, was es steuert.
Schalten Sie **Meta-Daten** ein, um Schlüssel-Wert-Konfigurationen — Limits, Tiernamen, Quoten — zu verknüpfen, die Ihrer Anwendung zusammen mit dem Flag geliefert werden. Siehe [Limits mit Metadaten anhängen](#attach-limits-with-metadata).
Klicken Sie auf **Bestätigen**. Das Flag erscheint in Ihrer Berechtigungsliste, bereit, mit Produkten verknüpft zu werden.
## An ein Produkt anhängen
Öffnen Sie ein Produkt (oder erstellen Sie eines), finden Sie die **Berechtigungen**-Karte und klicken Sie auf **+**, um bestehende Berechtigungen zu verknüpfen. Wählen Sie Ihr Feature-Flag und klicken Sie auf **Fertig**.
Das verknüpfte Flag erscheint im Produktformular, und die Checkout-Vorschau listet es unter **Enthalten**.
## Erforderliche Konfiguration
| Feld | Erforderlich | Beschreibung |
| -------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `feature_id` | Ja | Kennung, die Ihre Anwendung überprüft, z.B. `advanced_reports`. Nicht einzigartig für Berechtigungen. |
| `feature_type` | Ja | Typ der verliehenen Fähigkeit. Heute wird nur `boolean` unterstützt. |
### Erstellung über API
```typescript TypeScript theme={null} theme={null}
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,
},
});
```
```python Python theme={null} theme={null}
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,
},
)
```
```go Go theme={null} theme={null}
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"),
},
),
})
```
***
## Limits mit Metadaten anhängen
Ein boolesches Flag beantwortet "Hat dieser Kunde die Funktion?". Metadaten beantworten "Mit welcher Konfiguration?". Berechtigungsmetadaten akzeptieren Zeichenfolgen, Ganzzahlen, Zahlen und boolesche Werte, und jede Berechtigung nimmt einen **eingefrorenen Schnappschuss** der Metadaten der Berechtigung zum Zeitpunkt ihrer Erstellung auf.
Dieses Schnappschussverhalten macht Metadaten sicher für Planlimits einsetzbar:
* Das spätere Bearbeiten der Metadaten der Berechtigung betrifft nur **zukünftige** Berechtigungen. Kunden behalten die Limits, unter denen sie erworben haben.
* Der Schnappschuss wird bei jeder Berechtigung als sein Feld `metadata` zurückgegeben, sodass ein API-Aufruf sowohl das Flag als auch die Konfiguration liefert.
Beispielsweise kann ein `advanced_reports`-Flag mit `{ "tier": "pro", "monthly_report_limit": 100 }` Ihrer Anwendung erlauben, das Dashboard freizuschalten *und* das 100-Bericht-Quote ohne zweite Abfrage durchzusetzen. Wenn Sie das Limit später auf 250 erhöhen, bleiben bestehende Kunden bei 100, bis sie eine neue Berechtigung erhalten (zum Beispiel nach einem Planwechsel).
Verwenden Sie Metadaten für Limits und Konfigurationen; verwenden Sie `feature_id` nur für die Identität. Das Kodieren von Limits in der ID (`advanced_reports_100`) erzwingt ein neues Flag für jede Limitänderung und unterbricht die Prüfungen Ihrer Anwendung.
***
## Features eines Kunden überprüfen
Listen Sie die gelieferten Feature-Flag-Berechtigungen eines Kunden auf und erstellen Sie den Satz aktivierter Features. Der Endpunkt gibt eine Zeile pro Berechtigung über alle Berechtigungen zurück, die nach `integration_type` und `status` gefiltert werden können.
```typescript TypeScript theme={null} theme={null}
const features = new Map>();
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
}
```
```python Python theme={null} theme={null}
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")
```
```go Go theme={null} theme={null}
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
}
}
```
Die `feature`-Nutzlast wird nur bei `feature_flag`-Berechtigungen befüllt; sie ist `null` für jeden anderen Integrationstyp. Siehe die [List Customer Grants](/api-reference/entitlements/list-customer-grants) API-Referenz für die vollständige Antwortstruktur.
Das Überprüfen der API bei jeder Anfrage fügt Ihrem Hot Path Latenz hinzu. Cachen Sie die Feature-Menge pro Kunde mit einer kurzen TTL (Minuten, nicht Stunden) und ungültigen den Cache aus Ihrem Webhook-Handler, wenn sich der Status einer Berechtigung ändert — diese Kombination hält Prüfungen schnell und Widerrufe nahezu sofort.
***
## Lebenszyklus
Feature-Flag-Berechtigungen folgen dem Standard- [Berechtigungslebenszyklus](/features/entitlements/introduction#how-grants-work) mit einer Vereinfachung: Es gibt keinen Lieferstep, sodass Berechtigungen niemals in `pending` verbleiben und niemals zu `failed` wechseln.
| Auslöser | Effekt |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Einmalzahlung erfolgreich / Abonnement wird aktiv | Berechtigung erstellt mit `status: delivered` und `delivered_at` festgelegt. |
| Abonnement auf Eis gelegt, storniert oder abgelaufen | Berechtigung widerrufen mit passendem `revocation_reason`. |
| Rückerstattung bei einer Einmalzahlung | Berechtigung widerrufen mit `revocation_reason: refund`. |
| Abonnement erholt sich (zum Beispiel, dunning erfolgreich) | Die widerrufene Berechtigung wird zu `delivered` wiederhergestellt — gleiche Berechtigung `id`, Widerrufsfelder gelöscht. |
| Manueller API-Widerruf | Berechtigung widerrufen mit `revocation_reason: manual`. Wird bei Erneuerung nicht automatisch wiederhergestellt. |
Berechtigungen sind idempotent pro Berechtigung und Kunde: Solange ein Kunde eine nicht widerrufene Berechtigung für ein Flag hat, erzeugen wiederholte Käufe und Verlängerungen keine Duplikate.
***
## Webhooks
Abonnieren Sie die [`entitlement_grant.*`-Ereignisse](/developer-resources/webhooks/intents/entitlement-grant), um Flags in Ihre eigene Datenbank zu spiegeln, anstatt zu pollen:
* `entitlement_grant.created` — kommt bereits `delivered` mit der `feature`-Nutzlast an. Aktivieren Sie das Feature.
* `entitlement_grant.delivered` — wird ausgelöst, wenn eine zuvor widerrufene Berechtigung wiederhergestellt wird. Aktivieren Sie das Feature erneut.
* `entitlement_grant.revoked` — Zugriff entzogen. Deaktivieren Sie das Feature und überprüfen Sie `revocation_reason`, um Ihre Nachricht zu entscheiden.
```typescript TypeScript theme={null} theme={null}
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);
});
```
Es gibt keinen `entitlement_grant.failed` für Feature-Flags — die Lieferung erfolgt vollständig innerhalb Dodo Payments und kann nicht fehlschlagen.
***
## Beispiel: Pro-Plan schaltet erweiterte Berichte frei
1. **Erstellen Sie das Flag.** `feature_id: advanced_reports` mit Metadaten `{ "tier": "pro", "monthly_report_limit": 100 }`.
2. **Anhängen** an Ihr Pro-Plan-Abonnementprodukt.
3. **Ein Kunde abonniert.** Dodo Payments erstellt eine `delivered`-Berechtigung und löst `entitlement_grant.created` aus; Ihr Webhook-Handler aktiviert `advanced_reports` für den Kunden mit einem Limit von 100.
4. **Ihre App schaltet die Funktion ab.** Beim Laden des Dashboards, prüfen Sie die zwischengespeicherte Feature-Menge (oder rufen Sie `listEntitlementGrants` auf) und rendern Sie das Berichtsfeld nur, wenn `advanced_reports` vorhanden ist.
5. **Der Kunde storniert.** Dodo Payments widerruft die Berechtigung und löst `entitlement_grant.revoked` aus; Ihr Handler deaktiviert das Feature. Sollte der Kunde später durch Dunning erneut aktiviert werden, stellt `entitlement_grant.delivered` es wieder her — keine Codeänderungen erforderlich.
***
## Best Practices
* **Verwenden Sie stabile, snake\_case Feature-IDs.** Ihr Anwendungscode überprüft diese Strings; das Umbenennen eines davon ist eine Unterbrechung auf beiden Seiten.
* **Ein Flag pro Fähigkeit.** Bevorzugen Sie `advanced_reports` + `api_access` als zwei Berechtigungen über ein einziges `pro_bundle` — Widerrufungen und Plan-Mixe bleiben sauber.
* **Steuern Sie den Status über Webhooks, überprüfen Sie mit der API.** Webhooks halten Ihre Datenbank aktuell; der Endpunkt der Liste ist die Wahrheit für Abstimmungsjobs und Cache-Misses.
* **Behandeln Sie `revoked` als sofortig.** Ein widerrufenes Flag bedeutet, dass der Kunde nicht mehr für die Funktion bezahlt. Sperren Sie beim nächsten Anruf, nicht in der nächsten Sitzung.
* **Setzen Sie Limits in Metadaten, nicht im Code.** Eine Quote zu ändern, erfordert dann nur das Bearbeiten der Berechtigung — neue Kunden nehmen es automatisch auf, während bestehende Berechtigungen ihren erworbenen Schnappschuss behalten.