> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Features

> Erstelle und verwalte Features für deine Abo-Produkte.

# Übersicht

Die Features Integration ermöglicht es, dynamische Feature-Sets für deine Abonnement-Produkte zu erstellen und zu verwalten. Diese "Features" sind Leistungsmerkmale, die dein Produkt oder Service auszeichnen. Sobald ein Abonnement mit einem solchen Produkt erstellt wird – sei es über einen Checkout-Link oder manuell – werden die konfigurierten Features mit den entsprechenden Werten ins Abonnement übertragen.

### Use-Cases

* **SaaS-Lösungen**: Stelle für deine Kunden Feature-Sets wie Benutzeranzahl (Quantity), Funktions-Switches (z. B. "White Labeling aktiviert"), Custom-SLAs (Basic, Silber, Gold) oder Mengen-Ranges (z. B. "5 GB Speicherplatz") bereit.
* **Hosting- oder Server-Produkte**: Definiere RAM, CPU-Kerne, IP-Adressen als Features für Serverangebote.
* **Spezielle Zusatzfunktionen**: Ergänze individuelle Features (z. B. eine persönliche Onboarding-Session), um Kundenbedürfnisse flexibel zu erfüllen.

## Feature-Typen und Status

Features sind konfigurierbare Leistungsmerkmale für deine Abos, die in unterschiedlichen Typen erstellt werden können:

* **Switch**: Ein-/Ausschalten bestimmter Funktionalitäten.
* **Quantity**: Auswahl vordefinierter Mengen (z. B. "5 User", "10 User").
* **Custom**: Auswahl aus vorgegebenen Textwerten (z. B. "SLA Basic", "SLA Silber", "SLA Gold").
* **Range**: Manuelle Eingabe eines Wertes innerhalb eines bestimmten Rahmens, optional "unlimitiert" auf einer oder beiden Seiten.

Jedes Feature hat zudem einen Status:

* **Entwurf (Draft)**: Das Feature kann Produkten zugeordnet werden, wird aber noch nicht in Abos übernommen.
* **Aktiv (Active)**: Das Feature wird beim Erstellen eines neuen Abos übernommen.
* **Archiviert (Archived)**: Das Feature ist nicht mehr für neue Abos verfügbar, bleibt aber in bestehenden Abos unverändert.

<Tip>**Tipp:** Mit diesen Status kannst du Features vorab planen, testen und später aktivieren, ohne laufende Abos zu beeinflussen.</Tip>

## Beispiel für den Einsatz von Features

Stelle dir vor, du betreibst eine SaaS-Lösung mit dem Produkt "Professional". Dieses Produkt hat standardmäßig das Switch-Feature "White Labeling".

Für den Preis "jährlich" fügst du ein Custom-Feature "SLA Gold" hinzu.
Bucht ein Kunde das Produkt "Professional" mit dem Preis "jährlich", erhält er **automatisch** beide Features: White Labeling vom Produkt und SLA Gold vom Preis.

## Erstellen eines neuen Features

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Feature Übersicht öffnen">
        Wähle **Features** im Hauptmenü aus, um die Liste der Features anzuzeigen. Klicke auf **Neu**.
      </Step>

      <Step title="Feature konfigurieren">
        Fülle die Felder aus:

        * **Name**: Der Name des Features, z. B. "White Labeling". Dieser wird intern angezeigt und kann in Zukunft ggfs. auch im Kundenbereich sichtbar sein.
        * **Typ**: Wähle zwischen Switch, Quantity, Custom oder Range. Je nach Typ stehen weitere Einstellungen zur Verfügung.
        * **Beschreibung**: Eine kurze Beschreibung des Features, dies ist zur einfacheren internen Zuordnung gedacht.
        * **Status**: Wähle zwischen Entwurf, Aktiv oder Archiviert.
        * **Einheit**: Eine optionale Einheit, z. B. "User", "GB", "SLA", die bei Quantity oder Range verwendet wird und eine bessere Lesbarkeit und Verständlichkeit ermöglicht.
        * **Optionen**: Je nach Typ stehen weitere Einstellungen zur Verfügung, z. B. für Quantity die Auswahl der Mengen, für Range die Definition des Bereichs oder für Custom die Auswahl der Werte.
        * **Gültig ab**: Ein optionales Datum, ab dem das Feature aktiv ist und in neuen Abos übernommen wird. Für Bestandsabos ist dies nicht relevant.
        * **Gültig bis**: Ein optionales Datum, bis zu dem das Feature aktiv ist und in neuen Abos übernommen wird. Für Bestandsabos ist dies nicht relevant.
        * **Technische ID**: Eine optionale technische ID, die bspw. das Feature in deinem System identifiziert, z. B. "global.white-labeling".

        <Frame>
          <img src="https://mintcdn.com/fynnsubscriptionbilling/tzBoVhlU_naKbmRt/images/entitlements/feature-create.png?fit=max&auto=format&n=tzBoVhlU_naKbmRt&q=85&s=3c8338e886507ef0a2aa70c78d0ab66e" alt="Feature erstellen" width="1142" height="1722" data-path="images/entitlements/feature-create.png" />
        </Frame>
      </Step>

      <Step title="Feature speichern">
        Klicke auf **Feature erstellen**, um das Feature zu erstellen.

        Das Feature ist nun zur Zuordnung an Produkte und Preise bereit.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature erstellen](/api-reference/feature/create-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlements/features
    ```

    Alternativ kannst du die [Features abrufen](/api-reference/features/get-features), um die Liste der Features zu erhalten.
  </Tab>
</Tabs>

## Features zuordnen

Durch die Zuordnung von Features zu Produkten oder spezifischen Preisen stellst du sicher, dass bei der Erstellung eines Abonnements automatisch die relevanten Leistungsmerkmale übernommen werden.

* Features am **Produkt** sind immer gegeben.
* Durch Features am **Preis** können zusätzliche oder abweichende Eigenschaften ergänzt werden. Dies ermöglicht es, für jährliche Tarife z. B. zusätzliche Features zu definieren.
* Überschneidet sich ein Feature am Produkt und am Preis, gilt die Definition vom Preis.

Zusätzlich lassen sich Start- und Enddaten für Features festlegen, um Releases oder zeitlich begrenzte Aktionen vorzubereiten.

<Frame>
  <img src="https://mintcdn.com/fynnsubscriptionbilling/tzBoVhlU_naKbmRt/images/entitlements/feature-assignment-list.png?fit=max&auto=format&n=tzBoVhlU_naKbmRt&q=85&s=021d62aaa079a0e85e8061f698492fb6" alt="Liste der Feature-Zuordnung" width="2472" height="775" data-path="images/entitlements/feature-assignment-list.png" />
</Frame>

### Hinzufügen eines Features zu einem Produkt

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produkt bearbeiten">
        Navigiere zu **Produkte** und wähle das gewünschte Produkt aus.
      </Step>

      <Step title="Feature zum Produkt hinzufügen">
        Wähle nun das gewünschte Feature aus der Liste aus, setze den Wert und ggfs. die Gültigkeit.

        <Frame>
          <img src="https://mintcdn.com/fynnsubscriptionbilling/tzBoVhlU_naKbmRt/images/entitlements/assign-feature.png?fit=max&auto=format&n=tzBoVhlU_naKbmRt&q=85&s=ad60c9245af3e24b50c711687f4aae88" alt="Feature zum Produkt hinzufügen" width="1512" height="958" data-path="images/entitlements/assign-feature.png" />
        </Frame>
      </Step>

      <Step title="Feature speichern">
        Klicke auf **Speichern**, um das Feature dem Produkt zuzuweisen.
        Sollte das Feature zeitlich nicht eingeschränkt sein, wird dieses ab sofort in allen neuen Abos mit diesem Produkt übernommen.

        <Tip>
          Ist das Feature zeitlich eingeschränkt, wird es nur in neuen Abos übernommen, die in diesem Zeitraum erstellt werden.
        </Tip>

        <Info>
          Das Feature muss aktiv sein, um in neuen Abos übernommen zu werden. Es darf nicht archiviert oder im Entwurf sein.
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature zum Produkt hinzufügen](/api-reference/feature/assign-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlement/feature-assignments
    ```
  </Tab>
</Tabs>

### Hinzufügen eines Features zu einem Preis (optional)

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produkt bearbeiten">
        Navigiere zu **Produkte** und wähle das gewünschte Produkt aus.
      </Step>

      <Step title="Preis bearbeiten">
        Wähle den gewünschten Preis aus und klicke auf **Bearbeiten**.
      </Step>

      <Step title="Feature zum Preis hinzufügen">
        Wähle nun das gewünschte Feature aus der Liste aus, setze den Wert und ggfs. die Gültigkeit.

        <Frame>
          <img src="https://mintcdn.com/fynnsubscriptionbilling/tzBoVhlU_naKbmRt/images/entitlements/assign-feature.png?fit=max&auto=format&n=tzBoVhlU_naKbmRt&q=85&s=ad60c9245af3e24b50c711687f4aae88" alt="Feature zum Preis hinzufügen" width="1512" height="958" data-path="images/entitlements/assign-feature.png" />
        </Frame>
      </Step>

      <Step title="Feature speichern">
        Klicke auf **Speichern**, um das Feature dem Preis zuzuweisen.
        Sollte das Feature zeitlich nicht eingeschränkt sein, wird dieses ab sofort in allen neuen Abos mit diesem Produkt & Preis übernommen.

        <Tip>
          Ist das Feature zeitlich eingeschränkt, wird es nur in neuen Abos übernommen, die in diesem Zeitraum erstellt werden.
        </Tip>

        <Info>
          Das Feature muss aktiv sein, um in neuen Abos übernommen zu werden. Es darf nicht archiviert oder im Entwurf sein.
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature zum Preis hinzufügen](/api-reference/feature/assign-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlement/feature-assignments
    ```
  </Tab>
</Tabs>

## Abonnements und Features

### Anlegen eines neuen Abonnements mit Features

Beim Erstellen eines neuen Abonnements oder Hinzufügen eines neuen Produktes, über die Web-App oder API werden automatisch alle Features des Produkts und des Preises übernommen.

<Note>
  Die Features werden nur beim Erstellen eines Abonnements übernommen. Änderungen an den Features im Produkt oder Preis wirken sich nicht auf bestehende Abos aus.
</Note>

### Hinzufügen individueller Features

Im Abonnement kannst du alle übernommenen Features einsehen, aktivieren/deaktivieren oder weitere Features hinzufügen, die nicht an ein Produkt oder einen Preis gebunden sind.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Features im Abo anpassen">
        1. Öffne das gewünschte Abo.
        2. Navigiere zum Reiter **Features**.
        3. Hier siehst du alle Features, ihre Herkunft und ihren Status.
        4. Klicke auf **Neues Feature hinzufügen**, um ein individuelles Feature hinzuzufügen.
        5. Speichere die Änderungen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature zum Produkt hinzufügen](/api-reference/feature/assign-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlement/feature-assignments
    ```
  </Tab>
</Tabs>

### Abrufen von Features in einem Abonnement

Um die Features eines Abonnements abzurufen, gibt es verschiedene Möglichkeiten:

#### Webhook abonnieren

Wir empfehlen die Abonnierung des `entitlement.state.updated` Webhooks, um bei Änderungen in den Features informiert zu werden.
Hierbei wird beim Hinzufügen, Entfernen eines Features (manuell oder durch Produkt-Änderung) am Abo ein Webhook ausgelöst.
Läuft ein Feature ab, oder wird es durch das "gültig ab" oder "gültig bis" Datum aktiviert/deaktiviert, wird ebenfalls ein Webhook ausgelöst.

Beispiel Payload:

```json theme={null}
{
    "event": {
      "id": "ad9f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
      "type": "entitlement.state.updated",
      "version": "v1",
      "createdAt": "2022-01-01T12:00:00Z"
    },
    "data": {
        "customer": {
            "id": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
            "customerNumber": "CUS-1234",
            [...]
        },
        "subscription": {
          "id": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
          "number": "SUB-1234",
          [...]
        },
        "entitlements": [
            {
                "entitlementId": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
                "featureId": "included-users",
                "featureName": "Included Users",
                "value": "5"
            },
            {
                "entitlementId": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
                "featureId": "addon-b",
                "featureName": "Addon B",
                "value": "true"
            },
            {
                "entitlementId": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
                "featureId": "sla-level",
                "featureName": "SLA Level",
                "value": "gold"
            }
        ]
    }
}
```

#### API-Endpunkt abrufen

Alternativ kannst du die Features eines Abonnements über den [Abonnement-Endpunkt](/api-reference/entitlement/get-available-features) abrufen.

<Info>
  Der Endpunkt ist auf 240 Anfragen pro Minute, pro Organisation begrenzt. Wir empfehlen daher die Verwendung des Webhooks.
</Info>

## Entitlement Status

Jedes Entitlement in einem Abonnement hat einen berechneten Status, der den aktuellen Zustand anzeigt:

* **Active**: Das Entitlement ist aktiv und liegt innerhalb des Gültigkeitszeitraums. Der Kunde kann das Feature nutzen.
* **Pending**: Das Entitlement ist aktiviert, aber das `validFrom`-Datum liegt in der Zukunft. Das Feature wird automatisch aktiv, sobald das Datum erreicht ist.
* **Disabled**: Das Entitlement wurde manuell deaktiviert.
* **Expired**: Das `validUntil`-Datum ist abgelaufen. Das Entitlement war aktiv, ist aber nicht mehr gültig.

<Note>
  Der Status wird automatisch basierend auf dem `active`-Flag und den Gültigkeitsdaten (`validFrom`, `validUntil`) berechnet. Bei Änderungen wird ein `entitlement.state.updated` Webhook ausgelöst.
</Note>

### Beispiel API-Response

```json theme={null}
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "feature": {
        "id": "white-labeling",
        "name": "White Labeling"
    },
    "value": "true",
    "validFrom": "2026-03-01T00:00:00Z",
    "validUntil": null,
    "active": true,
    "status": "pending"
}
```

In diesem Beispiel ist das Entitlement aktiviert (`active: true`), aber da `validFrom` in der Zukunft liegt, ist der Status `pending`.

## Abrufen von Kunden-Entitlements

Um die Entitlements eines Kunden abzurufen, muss sich der Kunde bspw. über [OAuth2](/guide/oauth2/introduction) oder einen generierten Access Token authentifizieren.

Der Abruf der aktuell aktiven Entitlements erfolgt anschließend über `https://coreapi.io/customer-entitlements` mit folgender Ausgabe:

```json theme={null}
{
  "subscriptionEntitlements": {
    "<subscriptionId>": [
        "my-feature1",
        "my-feature2",
        "my-feature3",
        "my-feature4"
    ]
  },
  "entitlements": [
    "my-feature1",
    "my-feature2",
    "my-feature3",
    "my-feature4"
  ]
}
```

Hierbei werden unter `entitlements` alle Entitlements der Abonnements zusammengeführt.

## Referenz zur API-Dokumentation

Eine ausführliche Referenz aller Endpunkte, Parameter und Rückgaben findest du in unserer [API-Dokumentation Features](/api-reference/feature) und [API-Dokumentation Entitlements](/api-reference/entitlement).

<Check>Mit der Features Integration kannst du flexibel und skalierbar die Funktionsumfänge deiner Produkte gestalten und dynamisch an deine Kunden ausliefern. Durch die Kombination aus Produkt- und Preis-Features sowie der individuellen Anpassbarkeit im Abonnement selbst stehen dir alle Möglichkeiten offen, um dein Angebot optimal auf die Bedürfnisse deiner Kunden abzustimmen.</Check>

## Webhooks

Folgende Webhooks sind für die Features-Integration verfügbar:

* `feature.created` - Ein neues Feature wurde erstellt.
* `feature.updated` - Ein Feature wurde aktualisiert.
* `feature.archived` - Ein Feature wurde archiviert.
* `entitlement.state.updated` - Die aktuell gültigen Features für ein Abonnement wurden aktualisiert (z.B. durch: eine Änderung des Abonnements; der Features; ein Feature wurde durch "gültig ab" / "gültig bis" hinzugefügt oder entfernt; ein Produkt wurde gekündigt / angepasst und entsprechend dessen Features). Siehe [Abrufen von Features in einem Abonnement](#webhook-abonnieren).