Diese Anleitung führt dich durch die Konfiguration von Lemon Squeezy als deinen Zahlungsanbieter. Am Ende wirst du einen funktionierenden Checkout-Fluss mit Webhook-Verarbeitung haben. Das Setup dauert etwa 20 Minuten.
Stell vor dem Start sicher, dass du das Getting Started-Setup abgeschlossen hast und deine Anwendung lokal läuft.
Konto & Store einrichten
1
Lemon Squeezy-Konto erstellen
Gehe zu lemonsqueezy.com und erstelle ein Konto. Lemon Squeezy fungiert als dein Merchant of Record — sie übernehmen die gesamte Steuerberechnung, -erhebung und -abführung über alle Rechtsbereiche hinweg.
2
Store erstellen
Erstelle nach der Registrierung einen neuen Store im Dashboard. Wähle einen Store-Namen, der zu deinem Produkt passt. Notiere die Store-ID aus den Store-Einstellungen — du wirst sie für die Umgebungsvariablen benötigen.
3
Test-Modus aktivieren
Schalte den Test-Modus im Lemon Squeezy-Dashboard um (Schalter oben rechts). Alle Produkte, Varianten und Webhooks, die du im Test-Modus erstellst, sind von den Produktionsdaten isoliert. So kannst du den vollständigen Zahlungsfluss ohne echte Abbuchungen testen.
Produkte erstellen
Erstelle ein Produkt für jede Abonnement-Stufe in deinem Lemon Squeezy-Dashboard. Kit verwendet drei bezahlte Stufen — Basic, Pro und Enterprise.
1
Zu Produkten navigieren
Gehe im Lemon Squeezy-Dashboard zu Store > Products und klicke auf New Product.
2
Basic-Produkt erstellen
Lege den Produktnamen fest (z. B. „Basic Plan"), füge eine Beschreibung hinzu und konfiguriere die Preisgestaltung. Wiederhole den Vorgang für Pro und Enterprise.
Verwende klare, beschreibende Produktnamen. Lemon Squeezy zeigt diese Namen auf der Checkout-Seite und in Kunden-E-Mails an. Du kannst das Checkout-Erscheinungsbild in den Store-Einstellungen anpassen.
Bonus-Credit-Produkte (nur credit-basiertes Modell)
Wenn du das credit-basierte Preismodell verwendest und Bonus-Credit-Aufladungen anbieten möchtest, erstelle zusätzliche Produkte für die Bonus-Pakete jeder Stufe. Diese müssen Einmalkauf-Produkte sein (keine Abonnements):
1
Bonus-Credit-Produkte erstellen
Erstelle für jede bezahlte Stufe (Basic, Pro, Enterprise) bis zu 2 Produkte, die die Credit-Pakete repräsentieren. Setze den Zahlungstyp auf einmalig (nicht wiederkehrend). Zum Beispiel:
| Produktname | Zahlungstyp | Preis | Credits |
|---|---|---|---|
| Basic 500 Credits | Einmalig | €4,99 | 500 |
| Basic 1200 Credits | Einmalig | €9,99 | 1.200 |
| Pro 2000 Credits | Einmalig | €9,99 | 2.000 |
| Pro 5000 Credits | Einmalig | €19,99 | 5.000 |
| Enterprise 8000 Credits | Einmalig | €19,99 | 8.000 |
| Enterprise 20000 Credits | Einmalig | €39,99 | 20.000 |
Jedes Produkt benötigt genau eine Variante. Passe Preise und Credit-Mengen an dein Geschäftsmodell an.
2
Variant-IDs notieren
Kopiere jede Variant-ID aus dem Lemon Squeezy-Dashboard. Du fügst diese als
NEXT_PUBLIC_BONUS_{TIER}_PACKAGE{N}_VARIANT_ID zu deinen Umgebungsvariablen hinzu. Die vollständige Liste der Bonus-Credit-Konfigurationsvariablen findest du unter Umgebungsvariablen.Bonus-Credit-Produkte müssen in Lemon Squeezy als Einmalkäufe konfiguriert sein. Sie werden über das
order_created-Webhook-Event verarbeitet, nicht über Abonnement-Events. Die Verwendung von wiederkehrender Abrechnung für Bonus-Credits führt zu einer falschen Webhook-Verarbeitung.Varianten erstellen
Varianten repräsentieren die spezifischen Preisoptionen innerhalb jedes Produkts. Die Anzahl der Varianten hängt von deinem Preismodell ab.
Klassisches SaaS (6 Varianten)
Klassisches SaaS erfordert 6 Varianten — monatliche und jährliche Abrechnung für jede bezahlte Stufe:
| Produkt | Variante | Abrechnung | Beispielpreis |
|---|---|---|---|
| Basic | Basic Monatlich | Monatlich | 9,99 $/Monat |
| Basic | Basic Jährlich | Jährlich | 99,99 $/Jahr |
| Pro | Pro Monatlich | Monatlich | 29,99 $/Monat |
| Pro | Pro Jährlich | Jährlich | 299,99 $/Jahr |
| Enterprise | Enterprise Monatlich | Monatlich | 99,99 $/Monat |
| Enterprise | Enterprise Jährlich | Jährlich | Nur auf Anfrage |
Für jedes Produkt klicke auf Variante hinzufügen und konfiguriere den Abrechnungszeitraum und den Preis. Notiere die Variant-ID jeder Variante — sichtbar in der URL der Variant-Einstellungen oder auf dem API-Tab.
Die Enterprise-Stufe ist typischerweise nur auf Anfrage erhältlich (kein Self-Service-Checkout). Du kannst trotzdem die Variante für API-basierte Bereitstellung erstellen oder die jährliche Enterprise-Variante komplett weglassen.
Credit-basiert (3 Varianten)
Credit-basiertes Pricing erfordert 3 Varianten — nur monatliche Abrechnung für jede bezahlte Stufe:
| Produkt | Variante | Abrechnung | Beispielpreis | Credits/Monat |
|---|---|---|---|---|
| Basic | Basic Monatlich | Monatlich | €9,90/Monat | 1.500 |
| Pro | Pro Monatlich | Monatlich | €19,90/Monat | 5.000 |
| Enterprise | Enterprise Monatlich | Monatlich | €39,90/Monat | 15.000 |
Credit-basiertes Pricing unterstützt keine jährliche Abrechnung — alle Abonnements verlängern sich monatlich mit Credit-Resets, die am Abrechnungszyklus ausgerichtet sind.
API-Key-Konfiguration
1
API-Key generieren
Gehe im Lemon Squeezy-Dashboard zu Settings > API und klicke auf Generate API Key. Gib ihm einen beschreibenden Namen wie „Kit Production" oder „Kit Development".
2
API-Key kopieren
Kopiere den generierten Key sofort — Lemon Squeezy zeigt ihn nur einmal an. Bewahre ihn sicher auf.
3
Zu Umgebungsvariablen hinzufügen
Füge den API-Key zu deiner Datei
apps/boilerplate/.env.local hinzu:bash
LEMONSQUEEZY_API_KEY="dein_api_key_hier"
Der
LEMONSQUEEZY_API_KEY ist ein serverseitiges Secret. Committe ihn niemals in die Versionskontrolle, gib ihn nicht in clientseitigem Code preis und teile ihn nicht öffentlich. Verwende apps/boilerplate/.env.local (das in .gitignore ist) für die lokale Entwicklung und die Umgebungsvariablen-Einstellungen deines Hosting-Anbieters für die Produktion.Webhook-Konfiguration
Webhooks sind die Art, wie Lemon Squeezy deine Anwendung über Abonnement-Events benachrichtigt. Kit verarbeitet 11 verschiedene Event-Typen über einen einzigen Endpunkt.
1
Webhook-Endpunkt erstellen
Gehe im Lemon Squeezy-Dashboard zu Settings > Webhooks und klicke auf Add Endpoint.
Setze die Webhook-URL auf:
https://deine-domain.com/api/webhooks/lemonsqueezy
Für die lokale Entwicklung benötigst du eine öffentlich zugängliche URL. Verwende einen Tunnel-Dienst wie ngrok:
bash
ngrok http 3000
Dann verwende die generierte ngrok-URL:
https://abc123.ngrok.io/api/webhooks/lemonsqueezy2
Webhook-Secret generieren
Lemon Squeezy generiert ein Signing-Secret für jeden Webhook-Endpunkt. Kopiere dieses Secret — es wird für die HMAC-SHA256-Signaturverifizierung verwendet, um sicherzustellen, dass Webhooks authentisch sind.
Füge es zu deiner
apps/boilerplate/.env.local hinzu:bash
LEMONSQUEEZY_WEBHOOK_SECRET="dein_webhook_secret_hier"
3
Webhook-Events auswählen
Aktiviere alle 11 Events, die Kit verarbeitet:
subscription_created, subscription_updated, subscription_cancelled, subscription_resumed, subscription_expired, subscription_paused, subscription_unpaused, subscription_payment_success, subscription_payment_failed, subscription_payment_recovered und order_created. Details zu jedem Event findest du unter Webhooks & Portal.Das
LEMONSQUEEZY_WEBHOOK_SECRET in deiner apps/boilerplate/.env.local muss exakt mit dem Signing-Secret aus dem Lemon Squeezy-Dashboard übereinstimmen. Wenn sie nicht übereinstimmen, schlagen alle Webhook-Anfragen bei der Signaturverifizierung fehl und geben 401-Fehler zurück. Kit verifiziert jeden Webhook mit HMAC-SHA256 vor der Verarbeitung.Checkliste Umgebungsvariablen
Hier ist der vollständige Satz zahlungsbezogener Umgebungsvariablen. Kopiere diesen Block in deine
apps/boilerplate/.env.local und fülle die Werte aus deinem Lemon Squeezy-Dashboard ein:# === Lemon Squeezy Core ===
LEMONSQUEEZY_API_KEY="lmsq_..."
LEMONSQUEEZY_STORE_ID="12345"
LEMONSQUEEZY_WEBHOOK_SECRET="whsec_..."
# === Pricing Model ===
NEXT_PUBLIC_PRICING_MODEL="classic_saas"
CURRENCY="EUR"
# === Classic SaaS Variant IDs ===
NEXT_PUBLIC_LEMONSQUEEZY_BASIC_MONTHLY_VARIANT_ID="123456"
NEXT_PUBLIC_LEMONSQUEEZY_BASIC_YEARLY_VARIANT_ID="123457"
NEXT_PUBLIC_LEMONSQUEEZY_PRO_MONTHLY_VARIANT_ID="123458"
NEXT_PUBLIC_LEMONSQUEEZY_PRO_YEARLY_VARIANT_ID="123459"
NEXT_PUBLIC_LEMONSQUEEZY_ENTERPRISE_MONTHLY_VARIANT_ID="123460"
# === Trial (Optional) ===
TRIAL_DAYS="14"
Test-Modus
Lemon Squeezy bietet eine vollständige Testumgebung. Alle Testdaten (Produkte, Abonnements, Webhooks) sind vollständig von der Produktion isoliert.
Test-Kreditkarten
Verwende diese Kartennummern im Test-Modus:
| Karte | Nummer | Ergebnis |
|---|---|---|
| Visa | 4242 4242 4242 4242 | Erfolgreiche Zahlung |
| Visa | 4000 0000 0000 0002 | Abgelehnte Zahlung |
| Mastercard | 5555 5555 5555 4444 | Erfolgreiche Zahlung |
Verwende ein beliebiges zukünftiges Ablaufdatum und eine beliebige 3-stellige CVC.
Webhook-Zustellung prüfen
Überprüfe nach dem Erstellen eines Test-Abonnements das Lemon Squeezy-Dashboard unter Settings > Webhooks. Jeder Endpunkt zeigt ein Zustellungsprotokoll mit:
- HTTP-Statuscode (sollte
200sein) - Antworttext
- Wiederholungsversuche (falls der Endpunkt nicht erreichbar war)
Kit gibt
200 für alle erfolgreich empfangenen Webhooks zurück, auch wenn der Handler auf einen internen Fehler stößt. Dies verhindert, dass Lemon Squeezy Webhooks, die empfangen wurden, aber nicht verarbeitet werden konnten, erneut versucht.Verifizierung
Überprüfe nach Abschluss des Setups, ob alles End-to-End funktioniert:
1
Entwicklungsserver starten
bash
pnpm dev:boilerplate
2
Tunnel starten (wenn Webhooks lokal getestet werden)
bash
ngrok http 3000
Aktualisiere die Webhook-URL im Lemon Squeezy-Dashboard auf deine ngrok-URL.
3
Test-Abonnement erstellen
Navigiere zur Abrechnungsseite in deiner Anwendung, wähle einen Plan und schließe den Checkout mit einer Test-Kreditkarte ab. Nach der Zahlung solltest du sehen:
- Einen
subscription_created-Webhook im Lemon Squeezy-Zustellungsprotokoll - Einen neuen
Subscription-Datensatz in deiner Datenbank - Die Stufe des Nutzers, aktualisiert in der
User-Tabelle - Initialisierte Credits (bei Verwendung des credit-basierten Modells)
4
Anwendungsstatus prüfen
Überprüfe, ob die Abrechnungsseite das aktive Abonnement widerspiegelt. Der Nutzer sollte seinen aktuellen Plan, das nächste Abrechnungsdatum und einen Link zum Kundenportal sehen.
Wenn keine Webhooks ankommen, prüfe: (1) Die Webhook-URL ist korrekt und öffentlich zugänglich, (2) das Signing-Secret stimmt mit deiner
apps/boilerplate/.env.local überein, (3) alle 11 Events sind im Dashboard ausgewählt. Kit protokolliert alle Webhook-Events in der Konsole — überprüfe deine Terminal-Ausgabe für detaillierte Debugging-Informationen.