Leitfaden: Produkt-Konfiguration im Abo-System (Entitlements & Credits)

Mit dem „Credit & Entitlement“-Architektur konfigurieren wir Produkte im Backend so, dass sie unsere interne Business-Logik (Kosten, Gutschriften, Feature-Freischaltungen) direkt steuern. Das System unterstützt dabei nahtlose Wechsel zwischen verschiedenen Ausbaustufen (Upgrades und Downgrades).

• creditPrice (Das „Chamäleon“-Feld für Credits): Dieses Feld steuert die Credit-Transaktionen, verhält sich aber abhängig von der Bezahlmethode und dem Abo-Typ unterschiedlich:
  • Kauf per internem Wallet (paidWithCredits = true): Der Wert definiert die reinen Kosten. Der Betrag wird vom Wallet abgebucht (bei Einmalkäufen oder zyklisch beim automatischen Renewal von internen Abos).
  • Kauf per Stripe / Echtgeld (paidWithCredits = false): Der Wert definiert das Credit-Äquivalent zur Echtgeldzahlung. Hierbei unterscheidet das System nach Typ:
    • Bei Credit-Abos (Auflade-Abos): Der Wert agiert als reines Auftanken und wird dem Wallet automatisch als WALLET_TOP_UP gutgeschrieben.
    • Bei Feature-Abos: Das System führt quasi einen Währungswechsel mit direkter Ausgabe durch. Der Betrag wird dem Wallet gutgeschrieben und im selben Zug für die Aktivierung des Features wieder abgebucht. Zudem bildet dieser Wert die zwingende Berechnungsgrundlage für anteilige Erstattungen (Proration Refunds) bei zukünftigen Level-Wechseln (Up- oder Downgrades).

• billingInterval (Zyklus): Optional. Gibt an, ob es sich um ein Abo handelt (z. B. „month“ oder „year“).
• additionalProperties → subscriptionInfo (Das Feature-Herzstück): Ein JSON-Objekt, das definiert, was das Entitlement (internes Abo) dem Nutzer exakt freischaltet.

Die subscriptionInfo steuert direkt die Berechtigungen (HostFeature) des Nutzers.

• type: Die Kategorieklammer (z.B. „credit“, „licence“, „visualizer“). Pro User und type gibt es immer maximal ein aktives Entitlement.
• level: Die Ausbaustufe. Höhere Level überschreiben niedrigere Level des gleichen Typs (und umgekehrt bei Downgrades).
• features: Ein Key-Value-Objekt für spezifische Rechte. Das Backend verarbeitet die Werte typisiert:
  • Boolean (true): Wird 1:1 als Flag übernommen (z. B. „panorama.model3ds“: true wird zu panorama.model3ds = „true“).
  • Number (Integer): Das Backend kombiniert den Key und die Number zu einem neuen Flag-String (z. B. „host.licences.visualizer“: 3 wird zu host.licences.visualizer3 = „true“).

Ein typisches Produkt für den Neueinstieg oder für Level-Wechsel (Up- und Downgrades).

• creditPrice: 50 (Kosten bei Wallet-Zahlung / Äquivalent-Wert bei Stripe-Zahlung für Währungswechsel und spätere Refunds)
• billingInterval: „month“
• subscriptionInfo:

"subscriptionInfo": {
  "type": "visualizer",
  "level": 3,
  "features": {
    "host.licences.visualizer": 3,
    "panorama.model3ds": true
  }
}

Was passiert? Das Backend bucht das Entitlement auf Typ „visualizer“ und schaltet in den HostFeatures host.licences.visualizer3 = „true“ sowie panorama.model3ds = „true“ frei. Alte Visualizer-Keys eines vorherigen Levels (z.B. visualizer2) werden dabei automatisch aufgeräumt.

Ein anderes levelbasiertes Abo mit jährlichem Abbuchungsinterval.

• creditPrice: 150
• billingInterval: „year“
• subscriptionInfo:

"subscriptionInfo": {
  "type": "licence",
  "level": 2,
  "features": {
    "host.licences.licence": 2
  }
}

Dieses Produkt existiert, um regelmäßig über Stripe bezahlt zu werden und dafür dem Nutzer Credits im Wallet gutzuschreiben.

• creditPrice: 100 (Da es ein „credit“ Typ ist, dient dies als reiner Auflade-Wert)
• billingInterval: „month“
• subscriptionInfo:

"subscriptionInfo": {
  "type": "credit",
  "features": {}
}

Was passiert? Der Nutzer bezahlt echtes Geld über Stripe. Der Webhook erkennt den Typ „credit“ und überspringt die direkte Wiederabbuchung. Der creditPrice von 100 bleibt als WALLET_TOP_UP im Wallet des Nutzers liegen. Proration-Refunds sind für diesen Typ automatisch deaktiviert.