Behandeln von Planänderungen

Weitere Informationen zu Upgrades und Downgrades in Bezug auf die Abrechnung findest du unter Verwenden der GitHub Marketplace-API in deiner App.

Schritt 1: Ereignis zur Preisplanänderung

GitHub sendet den marketplace_purchase-Webhook mit der changed-Aktion an deine App, wenn ein Kunde eine der folgenden Änderungen an seiner GitHub Marketplace-Bestellung vornimmt:

• Durchführen eines Upgrades auf einen teureren Preisplan oder eines Downgrades auf einen günstigeren Preisplan
• Hinzufügen oder Entfernen von Arbeitsplätzen zum bzw. aus dem vorhandenen Plan
• Ändern des Abrechnungszyklus

GitHub sendet den Webhook, wenn die Änderung wirksam wird. Wenn ein Kunde z. B. einen Plan herabstuft, sendet GitHub den Webhook am Ende des Abrechnungszyklus für den Kunden. Wenn ein Kunde ein Upgrade für seinen Plan durchführt, sendet GitHub sofort einen Webhook an deine App, damit der Kunde direkt auf den neuen Dienst zugreifen kann. Wenn ein Kunde von einem monatlichen zu einem jährlichen Abrechnungszyklus wechselt, wird dies als Upgrade betrachtet. Unter Abrechnung mit Kunden findest du weitere Informationen dazu, welche Aktionen als Upgrade oder Downgrade gelten.

Lies effective_date, marketplace_purchase und previous_marketplace_purchase aus dem marketplace_purchase-Webhook, um das Startdatum des Plans zu aktualisieren und Änderungen am Abrechnungszyklus und am Preisplan des Kunden vorzunehmen. Ein Beispiel für die Ereignisnutzdaten von marketplace_purchase findest du unter Webhook-Ereignisse für die GitHub Marketplace-API.

Wenn deine App kostenlose Testversionen anbietet, erhältst du den marketplace_purchase-Webhook mit der changed-Aktion, wenn die kostenlose Testversion abläuft. Wenn die kostenlose Testversion des Kunden abläuft, führe für den Kunden ein Upgrade auf die kostenpflichtige Version des kostenlosen Testplans durch.

Schritt 2: Aktualisieren von Kundenkonten

Du musst die Kontoinformationen des Kunden auf die Abrechnungszyklus- und Preisplanänderungen aktualisieren, die der Kunde an seiner GitHub Marketplace-Bestellung vorgenommen hat. Zeige Upgrades auf den Preisplan, seat_count (für Preispläne pro Einheit) und Abrechnungszyklus auf der Website deiner Marketplace-App oder der Benutzeroberfläche deiner App an, wenn du den changed-Aktionswebhook erhältst.

Wenn ein Kunde einen Plan herabstuft, empfiehlt es sich, zu überprüfen, ob der Kunde die Grenzwerte des Plans überschritten hat. In diesem Fall solltest du direkt in deiner Benutzeroberfläche oder per Telefon oder E-Mail Kontakt aufnehmen.

Um Personen zum Upgrade zu ermuntern, kannst du eine Upgrade-URL in der Benutzeroberfläche deiner App anzeigen. Weitere Informationen findest du unter Informationen zu Upgrade-URLs.

Fehlerhafte Upgradezahlungen

Wenn ein Kunde ein Upgrade seines Plan ausführt und bei der Zahlung ein Fehler auftritt, setzt GitHub das GitHub Marketplace-Abonnement in den vorherigen Status zurück. GitHub sendet auch eine E-Mail an den Kunden, um ihn über den Fehler zu informieren und ihm zu ermöglichen, den Kauf erneut zu versuchen. Du erhältst einen Webhook mit der changed-Aktion, der dich zum Wiederherstellen des vorherigen Plans auffordert.

Informationen zu Upgrade-URLs

Über eine Upgrade-URL kannst du Benutzer von der Benutzeroberfläche deiner App umleiten, um ein Upgrade auf GitHub auszuführen:

https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID>

Wenn du beispielsweise feststellst, dass ein Kunde einen 5-Personen-Plan verwendet und zu einem 10-Personen-Plan wechseln muss, kannst du in der Benutzeroberfläche deiner App eine Schaltfläche mit dem Hinweis „Hier erhältst du Informationen zum Upgrade“ oder ein Banner mit einem Link zur Upgrade-URL anzeigen. Die Upgrade-URL führt den Kunden zur Upgradebestätigungsseite deines Listingplans.

Verwende die LISTING_PLAN_NUMBER für den Plan, den der Kunde erwerben möchte. Wenn du neue Preispläne erstellst, erhalten diese eine LISTING_PLAN_NUMBER, die für jeden Plan in deinem Listing eindeutig ist, sowie eine LISTING_PLAN_ID, die für jeden Plan im GitHub Marketplace eindeutig ist. Du kannst diese Nummern finden, indem du Pläne auflistest. Dadurch werden die Preispläne deines Listings identifiziert. Verwende die LISTING_PLAN_ID und den Endpunkt GET /marketplace_listing/plans/{plan_id}/accounts, um die CUSTOMER_ACCOUNT_ID zu erhalten.