So pausieren oder kündigen Sie Kundenabonnements über die API in 4Geeks Payments

🤖 Erklären mit KI

Die effiziente Verwaltung des Kundenlebenszyklus ist für moderne SaaS- und abonnementbasierte Unternehmen von entscheidender Bedeutung. Während die 4Geeks Console eine benutzerfreundliche Oberfläche für die manuelle Verwaltung bietet, erfordert die Skalierung des Betriebs häufig eine programmgesteuerte Steuerung. 4Geeks Payments bietet eine robuste API, mit der Entwickler Abonnements automatisch pausieren oder kündigen können, die sich nahtlos in Ihre eigenen Kundenportale oder internen Verwaltungstools integrieren lässt.

Dieser Artikel führt Sie durch die technischen Schritte zum Pausieren oder Kündigen von Kundenabonnements mithilfe der 4Geeks Payments API, um sicherzustellen, dass Ihre Abrechnungslogik korrekt und Ihr Kundenerlebnis nahtlos bleibt.

Voraussetzungen¶

Bevor Sie mit der API interagieren, stellen Sie sicher, dass Sie über Folgendes verfügen:

• Aktives 4Geeks Payments-Konto: Das Modul 4Geeks Payments muss in Ihrem Konto aktiviert sein.
• API-Anmeldeinformationen: Ihr API Key und Ihr Secret sind für die Authentifizierung erforderlich. Diese können im Abschnitt Developers der 4Geeks Console generiert werden.
• Abonnement-ID: Die eindeutige Kennung (subscription_id) für das spezifische Kundenabonnement, das Sie ändern möchten.
• API-Client: Ein Tool wie Postman, cURL oder Ihre bevorzugte Programmiersprache (Python, Node.js usw.) zum Senden von HTTP-Anfragen.

Schritt-für-Schritt-Anleitung¶

Schritt 1: Authentifizieren Sie Ihre Anfrage¶

Alle API-Anfragen an 4Geeks Payments müssen authentifiziert werden, um die Sicherheit zu gewährleisten. Sie authentifizieren sich mithilfe eines Bearer-Tokens im Header Ihrer Anfrage.

1. Suchen Sie Ihre API-Anmeldeinformationen im Reiter Settings > Developers des Dashboards.
2. Fügen Sie den folgenden Header in Ihre HTTP-Anfrage ein: Authorization: Bearer YOUR_API_KEY

Schritt 2: Abrufen der Abonnement-ID¶

Um ein Abonnement zu ändern, müssen Sie es zuerst identifizieren. Wenn Sie die ID noch nicht in Ihrer Datenbank gespeichert haben, können Sie sie abrufen, indem Sie die Abonnements für einen bestimmten Kunden auflisten.

1. Senden Sie eine GET-Anfrage an den Endpunkt: https://api.4geeks.io/v1/subscriptions.
2. Filtern Sie nach der E-Mail-Adresse oder der eindeutigen Kunden-ID des Kunden.
3. Kopieren Sie aus der JSON-Antwort die Zeichenfolge id (z. B. sub_1a2b3c4d5e).

Schritt 3: Pausieren eines Abonnements¶

Das Pausieren ist ideal für vorübergehende Aussetzungen, bei denen Sie erwarten, dass der Kunde zurückkehrt. Es stoppt den Abrechnungszyklus, ohne das Abonnementobjekt zu löschen, was eine einfache Reaktivierung ermöglicht.

1. Endpunkt: Bereiten Sie eine POST-Anfrage vor an: https://api.4geeks.io/v1/subscriptions/{subscription_id}/pause
2. Body-Parameter (Optional): Sie können einen Parameter resume_at (Unix-Zeitstempel) angeben, wenn das Abonnement an einem bestimmten Datum automatisch reaktiviert werden soll.

   {
     "resume_at": 1735689600
   }
   

3. Ausführen: Senden Sie die Anfrage.
4. Verifizierung: Die API gibt das Abonnementobjekt mit dem Status paused zurück. Stellen Sie sicher, dass Ihr internes System die Zugriffsebene des Benutzers entsprechend aktualisiert.

Schritt 4: Kündigen eines Abonnements¶

Eine Kündigung beendet den Abrechnungszyklus dauerhaft. Je nach Konfiguration kann dies sofort oder am Ende des aktuellen Abrechnungszeitraums erfolgen.

1. Endpunkt: Bereiten Sie eine DELETE- (oder POST, je nach spezifischer Konfiguration) Anfrage vor an: https://api.4geeks.io/v1/subscriptions/{subscription_id}/cancel
2. Body-Parameter:
   • cancel_at_period_end (boolean): Setzen Sie dies auf true, damit der Kunde den Monat beenden kann, für den er bereits bezahlt hat. Setzen Sie dies auf false für einen sofortigen Widerruf.

     {
       "cancel_at_period_end": true
     }
     

3. Ausführen: Senden Sie die Anfrage.
4. Verifizierung: Die API gibt das Objekt mit dem Status canceled zurück (oder active mit einem Zeitstempel cancel_at, wenn Sie sich für eine Kündigung am Ende des Zeitraums entschieden haben).

Häufige Anwendungsfälle¶

Szenario 1: Die „Saisonale Pause“¶

Situation: Sie betreiben eine Bildungsplattform mit 4Geeks Payments und ein Schüler möchte sein Konto während der Sommerferien einfrieren, anstatt es vollständig zu kündigen. Anwendung: Ihr Schülerportal löst den Endpunkt Pause (/pause) mit einem Datum resume_at aus, das auf den 1. September festgelegt ist. Ergebnis: Die Abrechnung wird sofort gestoppt. Am 1. September reaktiviert die API das Abonnement automatisch und versucht, die Zahlung einzuziehen, wodurch der Kunde ohne manuelles Eingreifen gehalten wird.

Szenario 2: Automatisiertes Churn-Management¶

Situation: Ein Kunde klickt in Ihrem SaaS-Dashboard auf „Konto kündigen“. Anwendung: Ihr Backend löst den Endpunkt Cancel (/cancel) mit cancel_at_period_end: true aus. Ergebnis: Der Kunde behält den Zugriff, bis seine bezahlte Laufzeit abläuft. 4Geeks Payments stellt sicher, dass keine weiteren Rechnungen erstellt werden, und der Abonnementstatus wechselt schließlich automatisch zu canceled, wodurch Ihre Finanzunterlagen korrekt bleiben.

Fehlerbehebung¶

Problem 1: 401 Unauthorized Fehler¶

• Ursache: Ihr API Key fehlt, ist falsch oder abgelaufen.
• Lösung: Überprüfen Sie den Header Authorization. Generieren Sie Ihre Schlüssel bei Bedarf in der 4Geeks Console neu.

Problem 2: 404 Not Found¶

• Ursache: Die angegebene subscription_id existiert nicht oder gehört zu einer anderen Umgebung (z. B. Sandbox vs. Produktion).
• Lösung: Stellen Sie sicher, dass die ID mit der Umgebung übereinstimmt, die Sie abfragen. Stellen Sie sicher, dass Sie nicht versuchen, auf eine Live-ID in der Sandbox-Umgebung zuzugreifen.

Problem 3: Abonnementstatuskonflikt (409)¶

• Ursache: Sie versuchen, ein Abonnement zu pausieren, das bereits gekündigt ist, oder ein Abonnement zu kündigen, das bereits pausiert ist, ohne es zuerst zu reaktivieren.
• Lösung: Überprüfen Sie immer das Feld status des Abonnementobjekts über eine GET-Anfrage, bevor Sie eine Zustandsänderung versuchen, um sicherzustellen, dass die Aktion gültig ist.

Fazit¶

Die Automatisierung des Abonnementmanagements über die API ermöglicht es Ihrem Unternehmen, skalierende Kundenstämme präzise zu verwalten. Durch die Integration von Pausierungs- und Kündigungslogik direkt in Ihre Anwendungen entlasten Sie das Support-Personal und bieten Ihren Benutzern ein reibungsloseres Erlebnis.

Für fortgeschrittenere Konfigurationen, wie z. B. den Umgang mit Proratisierung bei Kündigungen oder die Einrichtung von Webhooks für Statusänderungen, erkunden Sie die Entwicklerdokumentation in der 4Geeks Console.

• Noch Fragen? Get support.
• Check out the changelog.