Zum Inhalt

Umgang mit Abonnement-Upgrades und -Downgrades mit Anteiliger Berechnung in 4Geeks Payments

🤖 Erklären mit KI

Die Verwaltung von Abonnement-Lebenszyklen ist ein kritischer Teil des Betriebs eines SaaS- oder Mitgliedschaftsgeschäfts. Wenn ein Kunde mitten in einem Abrechnungszyklus seinen Plan aktualisiert (Upgrade) oder herabstuft (Downgrade), übernimmt 4Geeks Payments automatisch die anteilige Berechnung (Proration). Dies stellt sicher, dass Ihre Kunden fair belastet werden – sie zahlen nur für die Zeit, die sie jeden Plan genutzt haben –, ohne dass Sie manuelle Berechnungen durchführen oder separate Erstattungen ausstellen müssen.

Dieser Leitfaden erklärt, wie Sie ein Abonnement mithilfe der 4Geeks Payments API programmgesteuert aktualisieren oder herabstufen und wie das System die resultierenden anteiligen Gebühren oder Gutschriften berechnet.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

  • Ein 4Geeks Payments-Konto: Sie müssen über ein aktives Händlerkonto verfügen.
  • API-Schlüssel: Ihre sk_test_ (für Sandbox) oder sk_live_ (für Produktion) Schlüssel.
  • Abonnement-ID: Die eindeutige Kennung (UUID) des Abonnements, das Sie ändern möchten.
  • Plan-ID: Die eindeutige Kennung des neuen Plans, zu dem der Kunde wechselt.
  • Zugriff auf 4Geeks Console: Melden Sie sich an, um Änderungen zu verwalten und zu überprüfen.

So aktualisieren Sie ein Abonnement

4Geeks Payments vereinfacht Änderungen, indem Upgrades und Downgrades als Aktualisierung des bestehenden Abonnementobjekts behandelt werden. Das System erkennt automatisch die Preisdifferenz und wendet die erforderliche anteilige Berechnung an.

Schritt 1: Abrufen des aktuellen Abonnements

  1. Melden Sie sich bei der 4Geeks Console an.
  2. Navigieren Sie zum Modul Payments.
  3. Wählen Sie Subscriptions aus der Seitenleiste.
  4. Suchen Sie den Kunden per E-Mail oder ID, um seine aktiven Abonnements aufzulisten.
  5. Notieren Sie die subscription_id für das Abonnement, das Sie aktualisieren möchten.

Alternativ verwenden Sie die API, um Abonnements programmgesteuert abzurufen:

  • Endpunkt: GET https://api.4geeks.io/v1/subscriptions/?customer={customer_id}

Schritt 2: Aktualisieren des Abonnementplans

Senden Sie eine PUT-Anfrage an den Abonnement-Endpunkt mit der neuen plan_id. Dies löst die Prorations-Logik aus.

  1. Bereiten Sie Ihre API-Anfrage mit dem entsprechenden Schlüssel vor.
  2. Fügen Sie die neuen Plandetails in den Anfragetext ein.

Anfragebeispiel (mit cURL):

curl -X PUT "https://api.4geeks.io/v1/subscriptions/sub_123456789" \
  -u "sk_test_YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_new_tier_id"
  }'
  1. Senden Sie die Anfrage ab. Das System berechnet die Proration sofort für den aktuellen Abrechnungszyklus.

Tipp: Erwarten Sie bei Upgrades eine sofortige Rechnung. Bei Downgrades wird eine Gutschrift auf zukünftige Rechnungen angewendet. Vermeiden Sie das Mischen von Test- und Live-Modus-IDs, um Fehler zu vermeiden.

Schritt 3: Überprüfen der Prorations-Rechnung

  1. Überprüfen Sie die API-Antwort auf die aktualisierten Abonnementdetails, einschließlich der latest_invoice.
  2. Gehen Sie in der 4Geeks Console zu Invoices, um die neue anteilige Rechnung anzuzeigen.
  3. Bestätigen Sie den Status (z. B. “paid” oder “open”) und den fälligen Betrag.

Antwortbeispiel (Vereinfachtes JSON):

{
  "id": "sub_123456789",
  "status": "active",
  "plan": {
    "id": "plan_new_tier_id",
    "name": "Pro Plan",
    "amount": 50.00
  },
  "current_period_end": "2023-12-01T00:00:00Z",
  "latest_invoice": {
    "id": "inv_987654321",
    "amount_due": 15.50,
    "status": "paid"
  }
}

Best Practice: Überwachen Sie Webhooks auf Ereignisse wie invoice.created oder invoice.payment_succeeded, um Benachrichtigungen oder Aktualisierungen in Ihrem System zu automatisieren.

Häufige Anwendungsfälle

Szenario 1: Upgrade mitten im Zyklus (Sofortige Belastung)

Ein Kunde mit einem 10 $/Monat Basis-Plan aktualisiert zur Monatsmitte auf den 30 $/Monat Pro-Plan.

  • Das System schreibt ~5 $ für ungenutzte Basis-Zeit gut und berechnet ~15 $ für die verbleibende Pro-Zeit.
  • Ergebnis: Sofortige 10 $-Rechnung. Keine Dienstunterbrechung, und der Abrechnungszyklus bleibt gleich.

Dies stellt Kunden zufrieden, indem es sofortigen Zugriff auf neue Funktionen bietet und gleichzeitig eine faire Abrechnung gewährleistet.

Szenario 2: Downgrade mitten im Zyklus (Gutschrift angewendet)

Ein Kunde stuft zur Hälfte von 30 $/Monat Pro auf 10 $/Monat Basis herunter.

  • Gutschrift von ~15 $ für ungenutzte Pro-Zeit und Berechnung von ~5 $ für verbleibende Basis-Zeit.
  • Ergebnis: 10 $ Gutschrift im Guthaben des Kunden gespeichert, angewendet auf die nächste Rechnung.

Ideal, um Kunden zu binden, die Flexibilität benötigen, ohne zu viel zu bezahlen.

Fehlerbehebung

Problem 1: API gibt 404 Not Found zurück

  • Ursache: Falsche subscription_id oder plan_id.
  • Lösung: Überprüfen Sie die IDs in der 4Geeks Console. Stellen Sie die Konsistenz zwischen Test-/Live-Modus sicher.

Problem 2: Upgrade-Rechnung schlägt fehl (402 Payment Required)

  • Ursache: Die Karte des Kunden lehnt die anteilige Belastung ab.
  • Lösung: Überprüfen Sie den Status von latest_invoice. Fordern Sie den Kunden auf, seine Zahlungsmethode über den Link zum Kundenportal zu aktualisieren.

Problem 3: Keine Belastung sichtbar für Downgrade

  • Ursache: Downgrades erstellen Gutschriften, keine sofortigen Rückerstattungen.
  • Lösung: Überprüfen Sie das Guthaben des Kunden in der API oder 4Geeks Console. Gutschriften werden automatisch auf zukünftige Rechnungen angewendet.

Fazit

Mit 4Geeks Payments ist der Umgang mit Abonnementänderungen nahtlos und automatisiert, was den Verwaltungsaufwand reduziert und die Kundenzufriedenheit verbessert. Implementieren Sie diese Schritte, um Upgrades und Downgrades effizient zu verwalten. Für eine fortgeschrittenere Automatisierung erkunden Sie die Integration mit 4Geeks AI Agents.

Zusätzliche Ressourcen