billing

Abrechnung und Abonnementverwaltung

TanStack Ship Abrechnungssystem fuer Stripe-Abonnementverwaltung, wiederkehrende Zahlungsabwicklung, Rechnungserstellung und Kunden-Self-Service-Portal.

Stripe Checkout-Integration fuer sichere Zahlungsabwicklung

Abonnementplan-Verwaltung mit monatlichen und jaehrlichen Abrechnungszyklen

Automatische wiederkehrende Abrechnung mit Webhook-gesteuerter Zustandssynchronisation

Kundenportal zur Selbstverwaltung von Abonnements

Dynamische Preisberechnungs-Engine mit Gutschein-, Bonuspunkt- und UTM-basierter Rabattunterstuetzung

Umfassende Rechnungshistorie und Zahlungsabstimmung

Bonuspunkte als alternative Zahlungsmethode

Mehrwaehrungs- und Multi-Plan-Abonnementkatalogverwaltung

Auch verfügbar auf:English·中文

Ueberblick

Das Abrechnungs- und Abonnementverwaltungssystem in TanStack Ship bietet eine komplette, produktionsreife Loesung fuer den gesamten Abonnement-Lebenszyklus. Angetrieben durch die Stripe-Integration verwaltet es alles — vom initialen Checkout und wiederkehrenden Zahlungen bis hin zur Rechnungserstellung, Rabattanwendung und Kunden-Self-Service.

Ob Ihr SaaS-Geschaeft monatliche Abonnements, Jahresplaene mit Rabatten oder einmalige Kaeufe anbietet, die Abrechnungsengine passt sich dynamisch an Ihre Preisstrategie an. Das System wurde mit Zuverlaessigkeit als Grundlage konzipiert — Webhook-gesteuerte Zustandssynchronisation stellt sicher, dass Zahlungsereignisse nie verloren gehen, und idempotente Operationen verhindern doppelte Verarbeitung.

Als Teil der TanStack Ship Plattform integriert sich das Abrechnungsmodul nahtlos in das Guthabensystem, die Kampagnen- und Angebotsverwaltung, das UTM-Tracking und die Umsatzanalyse-Dashboards.

Design-Ablauf

Der Abonnement-Lebenszyklus folgt einem klar definierten Ablauf von der Planauswahl bis zur wiederkehrenden Abrechnung:

Design-Philosophie

Das Abrechnungssystem basiert auf drei Kernprinzipien:

Zuverlaessigkeit zuerst — Webhook-gesteuerte Zustandssynchronisation stellt sicher, dass jedes Zahlungsereignis erfasst wird, selbst bei voruebergehenden Netzwerkausfaellen. Idempotente Operationen verhindern doppelte Verarbeitung bei Webhook-Wiederholungen.
Zero-Trust-Preisgestaltung — Alle Preisberechnungen erfolgen serverseitig beim Checkout, nicht auf dem Client. Dies verhindert Manipulationen und gewaehrleistet eine konsistente, pruefbare Preislogik fuer alle Benutzer. Im Gegensatz zu Paddle oder Chargebee — die als externe Abrechnungsplattformen mit Weiterleitungs-basierten Checkout-Ablaeufen arbeiten — integriert unser Abrechnungssystem Stripe Checkout direkt in Ihre Anwendungsrouten, wobei die Preislogik in Ihrer eigenen Serverumgebung laeuft fuer vollstaendige Kontrolle ueber Rabattzusammensetzung, Guthabenanwendung und UTM-basierte Preisgestaltung.
Komponierbare Rabattarchitektur — Rabatte aus mehreren Quellen (Gutscheine, Guthaben, UTM-Kampagnen, Feiertagsraten) werden in einer definierten Prioritaetskette ausgewertet. Jede Quelle addiert oder subtrahiert unabhaengig und ermoeglicht komplexe Werbestrategien ohne Aenderung der Kernpreislogik.

Kernfunktionen

Stripe Checkout-Integration

Das System verwendet Stripe Checkout Sessions fuer sichere, PCI-konforme Zahlungsabwicklung. Wenn ein Benutzer auf der Preisseite einen Plan auswaehlt, erstellt der Server eine Checkout Session mit der entsprechenden Preis-ID, Kundenmetadaten sowie Erfolgs- und Abbruch-URLs.

Zahlungsablauf:

Benutzer waehlt einen Plan auf der Preisseite aus
Server erstellt eine Stripe Checkout Session via POST /api/stripe/checkout
Benutzer wird zur gehosteten Stripe-Checkout-Seite weitergeleitet
Nach erfolgreicher Zahlung leitet Stripe zurueck zur Anwendung
Stripe Webhook unter /api/stripe/webhook aktualisiert den Abonnementstatus in der Datenbank
Das Dashboard des Benutzers zeigt sofort den neuen Plan und Abonnementstatus an

Der Checkout-Endpunkt unterstuetzt optionale Gutscheincodes, Testzeitraeume und vorausgefuellte Kundeninformationen fuer wiederkehrende Benutzer.

Beispiel — Checkout-API-Antwort:

json

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "sessionId": "cs_test_...",
  "plan": "Pro Monthly",
  "amount": 2900,
  "currency": "usd",
  "discounts": ["WELCOME20"]
}

Clientseitiges Preiskarten-Beispiel:

tsx

import { useMutation } from '@tanstack/react-query'
import { useNavigate } from '@tanstack/react-router'

export function PricingCard({ plan }: { plan: { id: string; name: string; price: number } }) {
  const navigate = useNavigate()

  const checkout = useMutation({
    mutationFn: async () => {
      const res = await fetch('/api/stripe/checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ priceId: plan.id }),
      })
      const data = await res.json() as { url: string }
      window.location.href = data.url
    },
  })

  return (
    <div className="rounded-lg border p-6 text-center">
      <h3 className="text-lg font-semibold">{plan.name}</h3>
      <p className="mt-2 text-3xl font-bold">${plan.price}<span className="text-sm font-normal text-muted-foreground">/Monat</span></p>
      <button
        className="mt-4 w-full rounded-md bg-primary py-2 text-white"
        onClick={() => checkout.mutate()}
        disabled={checkout.isPending}
      >
        {checkout.isPending ? 'Weiterleitung...' : 'Abonnieren'}
      </button>
    </div>
  )
}

Abonnementplan-Verwaltung

Zwei Abonnementstufen sind standardmaessig verfuegbar, beide vollstaendig ueber das Stripe Dashboard konfigurierbar:

Monatlich — Standard-wiederkehrende Abrechnung mit monatlichen Zyklen, ideal fuer Benutzer, die Flexibilitaet bevorzugen
Jaehrlich — Rabattierte Preisgestaltung mit jaehrlicher Abrechnung, die typischerweise etwa 20% Ersparnis gegenueber der monatlichen Abrechnung bietet

Plaene werden als Stripe-Produkte mit zugehoerigen Preisen definiert. Das System cacht den Produktkatalog auf dem Server und stellt ihn ueber /api/billing/catalog fuer die clientseitige Darstellung auf der Preisseite bereit. Dieser Katalog-Endpunkt unterstuetzt Echtzeit-Preisberechnung unter dynamischer Beruecksichtigung aktiver Rabatte und Sonderangebote.

Kunden-Self-Service-Portal

Benutzer koennen ihr Abonnement verwalten, ohne die Anwendung verlassen zu muessen — ueber das Stripe-Kundenportal, das vom Dashboard aus zugaenglich ist. Das Portal unterstuetzt:

Anzeigen aktueller Plandetails und des Abonnementstatus
Upgrade oder Downgrade zwischen verfuegbaren Plaenen
Sichere Aktualisierung der Zahlungsmethode
Vollstaendige Rechnungs- und Zahlungshistorie einsehen
Kuendigung von Abonnements mit optionalen Bestaetigungsumfragen

Die Portalsitzung wird serverseitig erstellt und stellt eine sichere Authentifizierung sicher, bevor der Benutzer zur gehosteten Stripe-Verwaltungsoberflaeche weitergeleitet wird.

Dynamische Preisberechnungs-Engine

Die Preis-Engine unter src/lib/pricing-engine.ts berechnet Endpreise waehrend des Checkouts dynamisch. Sie evaluiert mehrere Rabattquellen in einer definierten Prioritaetsreihenfolge:

Basisplanpreis (monatlicher oder jaehrlicher Tarif)
Aktive Rabattangebote (prozentuale oder feste Gutscheinbetraege)
Bonuspunkte-Abzuege, die beim Checkout angewendet werden
UTM-Kampagnen-basierte Spezialpreise fuer verkehrsquellenspezifische Aktionen
Feiertags-Aktionstare fuer saisonale Kampagnen

Diese gestaffelte Berechnung stellt sicher, dass jeder Benutzer basierend auf seiner individuellen Kombination anwendbarer Rabatte den korrekten Endpreis sieht.

Rechnungs- und Zahlungsabstimmung

Jede Transaktion wird in der Datenbank aufgezeichnet und ist vom Benutzer-Dashboard aus zugaenglich. Das System verfolgt:

Zahlungsstatus: ausstehend, abgeschlossen, fehlgeschlagen, rueckerstattet
Zugehoerige Plandetails und Abrechnungszeitraum
Angewandte Rabatte, Bonuspunkte und Werbeanpassungen
Stripe Payment Intent IDs fuer finanzielle Abstimmung

Die Transaktionshistorie bietet eine vollstaendige Pruefkette fuer Buchhaltungs-, Compliance- und Kundendienstanforderungen.

Best Practices

Webhook-Zuverlaessigkeit

Konfigurieren Sie immer die Stripe-Webhook-Wiederholungseinstellungen im Stripe Dashboard. Das System ist darauf ausgelegt, doppelte Webhook-Zustellungen durch Idempotenzschluessel zu behandeln, aber die Aktivierung automatischer Wiederholungen (typischerweise 3 Versuche mit exponentiellem Backoff) stellt sicher, dass keine Umsatzverluste durch voruebergehende Netzwerkausfaelle entstehen.

Abonnementstatus-Abstimmung

Fuehren Sie regelmaessig Abstimmungsprozesse durch, die die Stripe-Abonnementstatus mit Ihren Datenbankdatensaetzen vergleichen. Dadurch werden Grenzfaelle erfasst, bei denen Webhook-Zustellungen waehrend kurzer Ausfaelle verloren gegangen sein koennten. Das Datenbankschema enthaelt last_synced_at-Zeitstempel, um dies zu erleichtern.

Testen mit Stripe-Testmodus

Verwenden Sie waehrend der Entwicklung den Stripe-Testmodus mit Testkartennummern (z. B. 4242 4242 4242 4242 fuer erfolgreiche Zahlungen, 4000 0000 0000 0002 fuer abgelehnte Karten). Das TanStack Ship-Abrechnungs-Seed-Skript (npm run db:seed:billing) befuellt Beispielprodukte und -preise fuer Tests mit.

Umgang mit fehlgeschlagenen Zahlungen

Konfigurieren Sie die Smart Retries-Funktion von Stripe, um fehlgeschlagene Zahlungen automatisch zu wiederholen. Das System verfolgt Zahlungsfehlerereignisse und kann E-Mail-Benachrichtigungen fuer Benutzer ausloesen, deren Abonnements eine Aktualisierung der Zahlungsmethode erfordern.

Haeufig gestellte Fragen

Wie richte ich Stripe zum ersten Mal ein? Konfigurieren Sie Ihren Stripe-Secret-Key, Webhook-Secret und Public-Key in der .dev.vars-Datei und fuehren Sie dann das Abrechnungs-Seed-Skript aus. Detaillierte Einrichtungsschritte finden Sie im Konfigurationsabschnitt unten.

Kann ich benutzerdefinierte Abonnementplaene erstellen, die ueber monatlich und jaehrlich hinausgehen? Ja. Plaene werden als Stripe-Produkte mit zugehoerigen Preisen definiert. Sie koennen jede Preisstruktur im Stripe Dashboard erstellen, einschliesslich vierteljaehrlicher, woechentlicher oder nutzungsbasierter Abrechnung.

Wie behandelt das System kostenlose Testphasen? Das System unterstuetzt die Testzeitraum-Funktionalitaet von Stripe. Wenn ein Benutzer einen Plan mit Testphase registriert, erhaelt er sofortigen Zugriff, waehrend die erste Zahlung bis zum Ende der Testphase aufgeschoben wird.

Was passiert bei fehlgeschlagenen Zahlungen? Stripe wiederholt fehlgeschlagene Zahlungen automatisch basierend auf Ihrem konfigurierten Wiederholungsplan. Das System verfolgt den Zahlungsstatus und aktualisiert das Abonnement entsprechend. Wenn alle Wiederholungen ausgeschoepft sind, wird das Abonnement als ueberfaellig markiert und schliesslich gekuendigt.

Koennen Benutzer beim Checkout Gutscheincodes anwenden? Ja. Der Checkout-Endpunkt akzeptiert einen optionalen Gutscheinparameter. Wenn ein gueltiger Gutscheincode in Stripe existiert, wird er vor der Zahlungsabwicklung auf die Checkout Session angewendet.

Wird Mehrwaehrung unterstuetzt? Ja. Stripe unterstuetzt mehrere Waehrungen. Sie koennen Preise in verschiedenen Waehrungen im Stripe Dashboard definieren, und die Katalog-API stellt alle verfuegbaren Preisoptionen bereit.

Wie werden Rueckerstattungen behandelt? Rueckerstattungen werden ueber das Stripe Dashboard bearbeitet. Wenn eine Rueckerstattung erfolgt, sendet Stripe ein charge.refunded-Webhook-Ereignis, und das System aktualisiert entsprechend den Transaktionsstatus in der Datenbank.

Ist das Abrechnungssystem in TanStack Ship fuer die Bereitstellung integriert? Ja. Das Abrechnungsmodul ist vollstaendig kompatibel mit TanStack Ship fuer die Produktionsbereitstellung. Umgebungsvariablen fuer Stripe-Schluessel werden ueber die TanStack Ship-Bereitstellungspipeline konfiguriert, was eine sichere Credential-Verwaltung ueber alle Umgebungen hinweg gewaehrleistet. Als leichte Alternative zu Next.js und Remix fuer Serverless-Edge-Deployment minimiert TanStack Ship den Bundle-Overhead bei voller Typsicherheit.

Konfiguration

Konfigurieren Sie die folgenden Umgebungsvariablen in .dev.vars:

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
VITE_STRIPE_PUBLIC_KEY=pk_live_...

Erstellen Sie dann Produkte und Preise im Stripe Dashboard und fuehren Sie das Abrechnungs-Seed-Skript aus:

bash

npm run db:seed:billing

Verwenden Sie fuer die lokale Entwicklung ohne Live-Stripe-Aufrufe Stripe-Testmodus-Schluessel. Der Webhook-Handler kann lokal mit der Stripe CLI getestet werden: stripe listen --forward-to localhost:3000/api/stripe/webhook.

Integrationspunkte

Das Abrechnungssystem integriert sich mit den folgenden TanStack Ship Plattformmodulen:

Kampagnen und Angebote — Rabattcodes werden waehrend des Checkouts ueber die Preis-Engine angewendet
Guthabensystem — Benutzer koennen Guthabenpunkte als alternative Zahlungsmethode fuer Abonnementkaeufe einsetzen
UTM-Kampagnen — Verkehrsquellenspezifische Preise werden von der Preis-Engine bei der Checkout-Session-Erstellung evaluiert
E-Mail-Marketing — Transaktions-E-Mails fuer Zahlungsbestaetigungen, Belege und Abonnement-Updates werden ueber das E-Mail-Kampagnensystem gesendet
Umsatzanalyse — Das Admin-Dashboard verfolgt MRR, ARR, Zahlungstrends und Kuendigungsraten
Benutzerverwaltung — Der Abonnementstatus bestimmt Benutzerrollenzuweisungen und Funktionszugriffsberechtigungen