Kostenlose Testversion in SaaS integrieren: Schritt-für-Schritt-Leitfaden mit Kinde

Die Integration einer kostenlosen Testversion in SaaS-Anwendungen stellt Entwickler oft vor unerwartete Herausforderungen. Viele Lösungen scheitern an ungenauen Synchronisationen zwischen Datenbanken, Abrechnungssystemen und Middleware – was zu inkonsistenten Nutzererfahrungen führt. Doch es gibt einen eleganteren Weg: die Nutzung von Kinde Workflows und Token-Claims, um die Trial-Logik zentral in der Zugriffsberechtigung zu verankern.

Warum klassische Trial-Implementierungen scheitern

Kostenlose Testversionen wirken auf den ersten Blick einfach umsetzbar: Ein Enddatum in der Datenbank speichern und bei jedem Request prüfen. Doch diese Methode stößt schnell an Grenzen. Häufige Probleme sind:

• - Zeitversätze: Cron-Jobs zur Downgradierung laufen zu einer festen Uhrzeit, während Nutzer in unterschiedlichen Zeitzonen aktiv sind.
• - Inkonsistente Prüfungen: Middleware prüft nur bestimmte API-Routen, während WebSocket-Verbindungen oder statische Seiten unberücksichtigt bleiben.
• - - Dateninkonsistenz: Der Trial-Status existiert in mehreren Systemen (Datenbank, Stripe, App-Middleware), die selten perfekt synchronisiert sind.

Die Folge? Nutzer erhalten Upgrade-Aufforderungen, obwohl sie bereits bezahlt haben – oder verlieren Zugriff, obwohl ihre Testphase noch läuft. Eine zuverlässige Lösung muss den Trial-Status an einer zentralen Stelle verwalten, die bei jedem Request verfügbar ist.

Kinde Billing: Native Trial-Unterstützung und ihre Grenzen

Kinde Billing bietet aktuell (Stand Mitte 2026) keine native Unterstützung für kostenlose Testversionen. Die Dokumentation listet dies als bekannte Einschränkung, die jedoch aktiv entwickelt wird. Dennoch lässt sich mit den vorhandenen Kinde-Komponenten eine robuste Trial-Lösung umsetzen – und diese bietet sogar mehr Flexibilität als eine integrierte Funktion.

Die in diesem Artikel beschriebene Architektur nutzt folgende Kinde-Primitives:

• - $0.00 Free-Plan: Ein kostenloser Tarif ohne Kartenzahlungspflicht.
• - Kinde Workflows: Automatisierte Aktionen nach der Nutzerauthentifizierung.
• - Benutzerdefinierte Claims: Trial-Startdatum in der Zugriffsberechtigung.
• - Feature-Flags: Steuerung des Funktionsumfangs während der Testphase.

Sobald Kinde native Trial-Unterstützung einführt, kann die bestehende Logik durch eine einfache Plan-Konfiguration ersetzt werden – ohne Änderungen am Frontend-Code.

Die vier Säulen der Trial-Architektur

Eine reibungslose kostenlose Testversion basiert auf vier zentralen Komponenten:

1. Kostenloser Tarif in Kinde Billing

Der erste Schritt ist die Einrichtung eines kostenlosen Tarifs, der als Container für die Testphase dient. Konfigurieren Sie ihn in Kinde Billing unter Billing → Plans → Add plan mit diesen Einstellungen:

Name: Free Trial (erscheint im Preismodell)
Beschreibung: 14 Tage voller Pro-Funktionen – ohne Kreditkarte
Schlüssel: free_trial (referenzierbar im Code, unveränderbar nach Veröffentlichung)
Tariftyp: Nutzer (für B2C) oder Organisationen (für B2B)

Anschließend fügen Sie eine Gebühr hinzu – selbst bei $0.00 Prämie. Wählen Sie Add charge und konfigurieren Sie:

Name: Basis-Abo-Gebühr
Betrag: $0.00
Intervall: Monatlich

der entscheidende Schritt: Deaktivieren Sie die Kartenzahlungspflicht unter Payment collection. Dies ist nur für Tarife mit $0.00-Gebühren möglich. Sobald Sie eine Gebühr über $0.00 hinzufügen, erzwingt Kinde die Kartenerfassung.

2. Feature-Flags für den Trial-Zugriff

Wechseln Sie in den Features-Bereich des Tarifs und verknüpfen Sie die Flags, die den Pro-Funktionsumfang während der Testphase freischalten. Beispiel:

• - advanced_analytics (boolescher Wert: true)
• - api_access (boolescher Wert: true)
• - export_data (boolescher Wert: true)

Diese Flags aktivieren sich automatisch für alle Nutzer des Free-Trial-Tarifs und können später für zahlende Kunden weiter genutzt werden.

3. Workflow für das Trial-Startdatum

Kinde Workflows ermöglichen es, nach der Authentifizierung eines Nutzers automatisch ein trial_start-Datum zu setzen. Erstellen Sie dazu einen neuen Workflow in Kinde unter Workflows → Add workflow und wählen Sie das Post-authentication-Trigger aus.

Fügen Sie eine Aktion hinzu, die ein benutzerdefiniertes Property setzt:

user.setProperty("trial_start", Math.floor(Date.now() / 1000));

Dieser Workflow wird nur beim ersten Login des Nutzers ausgeführt und speichert den Unix-Timestamp als Property. Das Property wird später in der Zugriffsberechtigung verfügbar sein.

4. Token-Claims für den Frontend-Zugriff

Damit Ihr Frontend den Trial-Status ohne Datenbankabfrage prüfen kann, müssen Sie die trial_start-Property und die aktuellen Feature-Flags in die Zugriffsberechtigung einbetten. Konfigurieren Sie dies in Kinde unter Authentication → Token customization.

Fügen Sie folgende Custom Claims hinzu:

{
  "trial_start": user.properties.trial_start,
  "feature_flags": {
    "advanced_analytics": user.feature_flags.advanced_analytics,
    "api_access": user.feature_flags.api_access
  }
}

Ihr Frontend kann diese Claims nun direkt aus dem Token auslesen, um den Trial-Status zu bestimmen.

Praktische Implementierung: Der useTrialStatus-Hook

In einer Next.js-Anwendung erstellen Sie einen React-Hook, der die Trial-Logik zentralisiert und alle UI-Entscheidungen steuert. Der Hook liest die Claims aus dem Token und berechnet den aktuellen Status:

import { useAuth } from "@kinde-oss/kinde-auth-react";

export function useTrialStatus() {
  const { isAuthenticated, user } = useAuth();
  
  if (!isAuthenticated) return { status: "inactive" };
  
  const trialStart = user?.properties?.trial_start;
  const now = Math.floor(Date.now() / 1000);
  const trialDuration = 14 * 24 * 60 * 60; // 14 Tage in Sekunden
  const trialEnd = trialStart + trialDuration;
  
  if (now < trialStart) return { status: "inactive" };
  if (now < trialEnd) return { status: "active", daysLeft: Math.ceil((trialEnd - now) / (24 * 60 * 60)) };
  if (user?.feature_flags?.advanced_analytics) return { status: "converted" };
  
  return { status: "expired" };
}

Dieser Hook kann nun in allen UI-Komponenten genutzt werden, um:

• - Eine Countdown-Banner anzuzeigen (z. B. "Noch 5 Tage kostenlos nutzen").
• - Upgrade-Aufforderungen an bestimmten Tagen zu zeigen (z. B. Tag 7 und Tag 13).
• - Gesperrte Funktionen mit einem Overlay zu versehen.
• - Nutzer nach Ablauf der Testphase automatisch auf den kostenpflichtigen Tarif umzuleiten.

Testing ohne Wartezeit

Die vollständige Testphase zu simulieren, erfordert keine 14-tägige Wartezeit. Nutzen Sie in Ihrer Entwicklungsumgebung:

• - Kinde’s Nicht-Produktionsumgebung für Workflows und Token-Customization.
• - Stripe Testmodus für Zahlungsabwicklungen.
• - Manuelle Anpassung des trial_start-Timestamps in den Nutzer-Properties (z. B. auf einen Tag in der Vergangenheit).

So können Sie Upgrade-Aufforderungen, gesperrte Inhalte und die automatische Tarifumstellung in Echtzeit testen.

Fazit: Trial-Management neu gedacht

Eine kostenlose Testversion muss keine Quelle für Frustration oder Support-Anfragen sein. Mit Kinde Workflows, Token-Claims und Feature-Flags lässt sich eine Lösung umsetzen, die zuverlässig, wartbar und zukunftssicher ist. Sobald Kinde native Trial-Unterstützung einführt, können Sie die bestehende Logik mit minimalem Aufwand migrieren – ohne Änderungen am Frontend. Der Schlüssel liegt darin, den Trial-Status an einer zentralen, immer verfügbaren Stelle zu verwalten: der Nutzerautorisierung.