Hinweis: Dieser Artikel gilt nur für die Veröffentlichung von Apps im GitHub Marketplace. Weitere Informationen zum Veröffentlichen von GitHub Actions im GitHub Marketplace findest du unter Aktionen auf dem GitHub-Marktplatz veröffentlichen.
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 erfährst du mehr darüber, 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 Nutzdaten des Ereignisses 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.
Hinweis: Es wird empfohlen, eine regelmäßige Synchronisierung über GET /marketplace_listing/plans/:id/accounts durchzuführen, um sicherzustellen, dass deine App für jedes Konto über den richtigen Plan, die korrekten Informationen zum Abrechnungszyklus und die richtige Einheitenanzahl (für Preise pro Einheit) verfügt.
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.
Hinweis: Wenn dein Kunde ein Upgrade auf zusätzliche Einheiten (z. B. Arbeitsplätze) durchführt, kannst du ihn zwar an den entsprechenden Plan für den Kauf verweisen, aber wir können unit_count-Parameter derzeit nicht unterstützen.