API und erweiterte Nutzung

Erfahren Sie mehr über erweiterte Strategien für die Verwendung von Test-Uhren im Dashboard und in der API.

Sie können eine Test-Uhr getrennt von einem Abonnement erstellen, um erweiterte Simulationen auszuführen. In diesem Szenario erstellen Sie zuerst die Test-Uhr und fügen dann verschiedene Testfälle hinzu.

Sie sind noch nicht bereit für eine vollständige Integration? Sehen Sie sich unseren Leitfaden zum Ausführen von Simulationen für Abonnements an.

So stellen Sie eine Test-Uhr ein, um die verstreichende Abo-Zeit zu simulieren.

Lebenszyklus der Test-Uhr

Folgen Sie dieser Anleitung, um mit der Verwendung von Test-Uhren zu beginnen:

Test-Uhr erstellen
Ihre Test-Simulation einrichten
Die Uhrzeit vorstellen
Änderungen überwachen und handhaben
Simulation aktualisieren
Die Uhr löschen

Sie können die Uhr vorstellen, Änderungen überwachen und die Simulation so oft aktualisieren, wie nötig ist, um verschiedene Fälle zu testen.

Uhr erstellen und ihre Zeit festlegen

Um eine Simulation zu starten, erstellen Sie eine Uhr und stellen Sie einen bestimmten Zeitpunkt für diese Uhr ein. Dies ist der zeitliche Startpunkt für alle Abonnements, die dieser Uhr zugeordnet sind. Dies kann ein Zeitpunkt in der Zukunft oder in der Vergangenheit sein, um verschiedene Simulationen zu testen, aber Sie können ihn nur zeitlich nach vorne verschieben, nachdem Sie ihn festgelegt haben.

Führen Sie die folgenden Schritte aus, um eine Test-Uhr im Dashboard zu erstellen. Erstellen Sie eine Sandbox, um Test-Uhren zu verwenden.

Gehen Sie zum Abschnitt Abonnements unter der Registerkarte Abrechnung.
Klicken Sie im Banner auf den Link zu Test-Uhren.
Klicken Sie auf Neue Simulation.
Geben Sie im Modal Neue Simulation erstellen einen Namen für die Simulation ein. Damit können Sie die Simulation beschreiben, die Sie testen, beispielsweise Annual renewal oder Free trial.
Stellen Sie einen bestimmten Zeitpunkt für die Uhr ein. Dies ist der Startpunkt Ihrer Simulation. Es kann ein Zeitpunkt in der Zukunft oder in der Vergangenheit sein. Sie können ihn jedoch nur zeitlich nach vorne verschieben, nachdem Sie ihn festgelegt haben.

Ihre Simulation einrichten

Als Nächstes richten Sie den Testfalls für Ihre Simulation ein. Zunächst müssen Sie einen Kunden/eine Kundin erstellen, für den/die Sie dann ein Abonnement erstellen.

So erstellen Sie einen Kunden/eine Kundin für Ihre Simulation über das Dashboard:

Rufen Sie die Seite Test-Uhren auf, um Ihre Test-Uhr zu finden.
Klicken Sie auf Hinzufügen > Kunden/Kundin hinzufügen.

Bei der Simulation von Test-Uhren können Sie keine bestehenden Kundinnen/Kunden auswählen. Sie können bis zu drei neue Kundinnen/Kunden zu jeder Simulation hinzufügen.

Sie können optional weitere verfügbare Eigenschaften für den Kunden/die Kundin eingeben, beispielsweise den Namen, die E-Mail-Adresse und die Rechnungsdaten. Diese Angaben sind jedoch nicht erforderlich. Für einige Simulationen, wie zum Beispiel das Testen kostenloser Testversionen, empfiehlt es sich nicht, Rechnungsdaten im Voraus zu erfassen.

Als Nächstes können Sie bis zu drei Abonnements oder Abonnementzeitpläne für Ihre Kundinnen/Kunden erstellen. So erstellen Sie über das Dashboard ein Abonnement für einen Kunden/eine Kundin:

Rufen Sie die Seite Test-Uhren auf, um Ihre Test-Uhr zu finden.
Klicken Sie auf Hinzufügen > Abonnement hinzufügen. Wählen Sie Ihren Kunden/Ihre Kundin über das Dropdown-Menü aus. Sie können den Kunden/die Kundin auch über die Kundenseite zu einem Abonnement hinzufügen, indem Sie auf Aktionen > Abonnement erstellen klicken.
Wählen Sie im Abschnitt Preisinformationen ein wiederkehrendes Produkt und einen Preis aus.
Definieren Sie für den Abonnementplan das Start- und Enddatum des Abonnements und wann der Abrechnungszyklus beginnen soll.
Wählen Sie eine Zahlungseinzugsmethode aus:
- Wählen Sie Automatisch die hinterlegte Zahlungsmethode belasten aus, wenn Sie das Kundenkonto zu Beginn des Abrechnungszyklus belasten möchten.
- Wählen Sie Rechnung zur manuellen Bezahlung per E-Mail an Kunden/Kundin senden aus, wenn Sie Ihrem Kunden/Ihrer Kundin eine Rechnung im Nachhinein stellen möchten.
Klicken Sie auf die Schaltflächen zum Starten des Test-Abos, um das Abonnement und den Abrechnungszyklus zu starten.

Sowohl das Kunden- als das auch Abonnementobjekt sind mit dem Uhrobjekt verknüpft, das Sie im ersten Schritt erstellt haben. Im Dashboard zeigt das Symbol an, dass ein Objekt mit einer Uhr verknüpft ist.

Simulierte Zeit vorstellen

Nachdem Sie die Test-Uhr erstellt und Ihren Testfall eingerichtet haben, stellen Sie die simulierte Zeit der Uhr vor. Wenn Sie dies zum ersten Mal tun, stellen Sie die Zeit ab der anfänglichen fixierten Zeit, die Sie bei Erstellung der Uhr festgelegt haben, vor. Wenn Sie die Zeit vorstellen, können Sie sehen, wie Ihre Integration funktioniert, wenn Abonnements enden, verlängert werden oder andere Änderungen daran vorgenommen werden (zum Beispiel ein Upgrade von einer kostenlosen Testversion auf ein kostenpflichtiges Abonnement).

Sie können Test-Uhren um jede beliebige Schrittweite vorstellen, aber jeweils nur um zwei Intervalle ab der ursprünglichen fixierten Zeit. Die Länge des Intervalls basiert auf dem kürzesten, mit der Test-Uhr verknüpften Abonnementintervall, das durch den wiederkehrenden Preis bestimmt wird. Wenn Sie beispielsweise ein Monatsabonnement haben, können Sie die Uhr jeweils nur bis zu zwei Monate vorstellen. Wenn für die Test-Uhr keine Abonnements oder Abonnementpläne vorhanden sind, können Sie sie bis zu zwei Jahre ab der ursprünglichen fixierten Zeit vorstellen.

So stellen Sie die Zeit über das Dashboard vor:

Rufen Sie die Seite Test-Uhren auf, um Ihre Test-Uhr zu finden.
Klicken Sie auf Vorlaufzeit.
Verwenden Sie das Kalender-Modal, um das Datum auszuwählen, auf das Sie die Uhr vorstellen möchten.
Klicken Sie auf Vorlauf.

Nachdem Sie Uhr vorgestellt wurde, wird das Banner aktualisiert, und die aktuelle Uhrzeit wird angezeigt.

Änderungen überwachen und verarbeiten

Nachdem eine API-Anfrage oder ein Dashboard-Vorgang erfolgreich durchgeführt wurde, dauert es einige Sekunden, bis die Uhr auf die angegebene Zeit vorgestellt wird. Um zu erfahren, wann sich der Status der Uhr geändert hat, können Sie Webhooks zur Überwachung von Ereignisbenachrichtigungen verwenden, oder Sie können die Uhr abfragen. Die Änderungen werden auch im Dashboard wiedergegeben. Sie können beispielsweise zur Rechnungsseite navigieren, um zu prüfen, ob eine Rechnung für Ihr Abonnement erstellt oder bezahlt wurde.

Wenn Sie Webhooks verwenden, überwachen Sie die folgenden Ereignisbenachrichtigungen. Stellen Sie vor dem Wechsel in die Produktionsumgebung sicher, dass Ihre Integration neben den unten aufgeführten auch die anderen abrechnungsspezifischen Ereignisbenachrichtigungen korrekt verarbeitet.

Ereignis	Beschreibung
`test_helpers.test_clock.advancing`	Das Vorstellen der Uhr hat begonnen, die angegebene Zeit wurde aber noch nicht erreicht.
`test_helpers.test_clock.ready`	Die Uhr wurde auf die angegebene Zeit vorgestellt.

Um den Status der Uhr abzufragen, können Sie diese anhand der ID abrufen, um ihren status zu überprüfen.

Simulation aktualisieren

Für Simulationen wie die Folgenden können Sie weiterhin Änderungen vornehmen und die Uhr vorstellen:

Hinzufügen eines Kundensaldos.
Upgrades in der Mitte eines Zyklus durchführen.
Einmalige Rechnungsposten hinzufügen.

Überwachen Sie die Änderungen nach jedem Update erneut. Wiederholen Sie diesen Vorgang so oft wie nötig, um die Anforderungen Ihres Testfalls zu erfüllen.

Uhr löschen

Test-Uhren werden automatisch 30 Tage nach ihrer Erstellung gelöscht. Sie können sie aber selbst löschen, sobald Sie mit dem Testen fertig sind, um für eine saubere Testumgebung zu sorgen.

So löschen Sie die Uhr und alle zugeordneten Testobjekte über das Dashboard:

Rufen Sie die Seite Test-Uhren auf, um Ihre Test-Uhr zu finden.
Klicken Sie auf Simulation abschließen.
Klicken Sie im Bestätigungs-Modal auf Abschließen.

Durch das Löschen der Uhr werden auch die mit der Uhr verknüpften Testkundinnen und Testkunden gelöscht und ihre Abonnements gekündigt. Test-Uhren sind nur in Sandboxes verfügbar. Sie können also keine Produktionsobjekte löschen, wenn Sie eine Uhr löschen.

Anwendungsfälle

Abonnementverlängerungen testen

Führen Sie zunächst die folgenden Schritte aus, um mit der Verwendung von Test-Uhren zu beginnen:

Test-Uhr erstellen
Ihre Test-Simulation einrichten
Die Uhrzeit vorstellen
Änderungen überwachen und handhaben
Simulation aktualisieren

Als Nächstes können Sie bestimmte Abonnementverlängerungen mithilfe von Test-Uhren testen. Angenommen, Sie möchten testen, ob ein Abonnement in Höhe von 50 USD/Monat korrekt verlängert wird. So simulieren Sie diese Situation mithilfe von Test-Uhren:

Erstellen Sie eine neue Test-Uhr und legen Sie ihre frozen_time auf den 1. Januar fest.
Fügen Sie einen Kunden/eine Kundin hinzu und fügen Sie eine Zahlungsmethode für den Kunden/die Kundin hinzu:

So fügen Sie eine Zahlungsmethode für einen Kunden/eine Kundin im Dashboard hinzu:

Klicken Sie auf der Kontoseite des Kunden/der Kundin im Abschnitt Zahlungsmethoden auf Hinzufügen > Karte hinzufügen.
Geben Sie Zahlungsinformationen ein. Verwenden Sie in diesem Fall die Testkarte.
Klicken Sie im Modal auf Karte hinzufügen.

Nachdem Sie eine Zahlungsmethode für den Kunden/die Kundin hinzugefügt haben, erstellen Sie ein Abonnement für den neuen Kunden/die neue Kundin mit einem Betrag von 50 USD/Monat. Dabei wird die Rechnung in Höhe von 50 USD automatisch bezahlt, und das Abonnement ist active.
Verschieben Sie das Datum auf den 1. Februar. Sie können sehen, dass eine Rechnung in Höhe von 50 USD erstellt wird. Standardmäßig wird die Rechnung eine Stunde lang im Status draft angezeigt.
Stellen Sie die Zeit um eine Stunde vor. Sie können sehen, dass die Rechnung automatisch finalisiert und bezahlt wird.

Upgrades in der Mitte eines Zyklus mit anteilsmäßigen Verrechnungen testen

Führen Sie zunächst die folgenden Schritte aus, um mit der Verwendung von Test-Uhren zu beginnen:

Test-Uhr erstellen
Ihre Test-Simulation einrichten
Die Uhrzeit vorstellen
Änderungen überwachen und handhaben
Simulation aktualisieren

Als Nächstes können sie anteilsmäßige Verrechnungen für Kundinnen und Kunden testen, die ihre Pläne in der Mitte eines Abrechnungszyklus aktualisieren. Angenommen, Sie haben zwei Produkte. Ein Produkt kostet 50 USD/Monat (‘basic plan’) und das andere 100 USD/Monat (‘premium plan’). In diesem Fall möchten Sie vielleicht die anteilsmäßige Verrechnung für einen Kunden/eine Kundin testen, der/die in der Mitte eines Abrechnungszyklus von einem ‘basic plan’ auf den ‘premium plan’ wechselt. So simulieren Sie diese Situation mithilfe von Test-Uhren:

Erstellen Sie eine neue Test-Uhr und legen Sie ihre frozen_time auf den 1. Januar fest.
Erstellen Sie einen Kunden/eine Kundin und fügen Sie seine/ihre Zahlungsmethode hinzu. Verwenden Sie in diesem Fall die Testkarte.
Erstellen Sie ein Abonnement für den ‘basic plan’ zu 50 USD/Monat. Danach können Sie sehen, dass die Rechnung über 50 USD/Monat erstellt, finalisiert und automatisch bezahlt wird.
Verschieben Sie das Datum um zwei Wochen. In diesem Fall setzen wir das Datum auf den 16. Januar.
Aktualisieren Sie das Abonnement auf einen ‘premium plan’ zu 100 USD/Monat:

So führen Sie ein Upgrade eines Abonnements über das Dashboard durch:

Klicken Sie auf der Kundenkontoseite oder der Seite mit den Abonnementdetails auf das Überlaufmenü eines Abonnements () und wählen Sie dann Abo aktualisieren aus.
Nehmen Sie Ihre gewünschten Änderungen vor.
Klicken Sie oben rechts auf Abonnement aktualisieren, um die Änderungen zu übernehmen.

Nach der Aktualisierung des Abonnements wird das Webhook-Ereignis customer.subscription.updated erstellt.
Für die anteilsmäßigen Verrechnungen werden auch ausstehende Rechnungsposten erstellt. Sie sehen eine negative anteilsmäßige Verrechnung in Höhe von -25 USD für die ungenutzte Zeit des ‘basic plan’ und eine positive anteilsmäßige Verrechnung in Höhe von 50 USD für die Nutzung des ‘premium plan’ für die Hälfte des verbleibenden Monats. Zu diesem Zeitpunkt wurde noch keine Rechnung erstellt.
Verschieben Sie das Datum um zwei Wochen. In diesem Fall setzen wir das Datum auf den 1. Februar. Sie können sehen, dass das Abonnement einen Zyklus durchlaufen hat. Es wurde eine Rechnung mit dem Status draft erstellt, die die ausstehenden Rechnungsposten, einschließlich einer negativen anteilsmäßigen Verrechnung, einer positiven anteilsmäßigen Verrechnung und der Gesamtzahlung für den Monat Februar enthält, was zu einem Betrag in Höhe von 125 USD führt. Standardmäßig wird die Rechnung etwa eine Stunde lang im Status draft angezeigt.
Um die Rechnung zu finalisieren, stellen Sie die Zeit um eine Stunde vor.

Testzeiträume

Führen Sie zunächst die folgenden Schritte aus, um mit der Verwendung von Test-Uhren zu beginnen:

Als Nächstes können Sie Testzeiträume mit Test-Uhren ausprobieren. Angenommen, Sie möchten, dass Ihre Kund/innen Ihr Produkt mit einem Sieben-Tage-Testzeitraum kostenlos ausprobieren, bevor Sie mit der Zahlung beginnen, und Sie möchten die Zahlungsinformationen im Voraus erfassen. Führen Sie die folgenden Schritte aus, um diese Situation mit Test-Uhren zu simulieren:

Erstellen Sie eine neue Test-Uhr und legen Sie ihre frozen_time auf den 1. Januar fest.
Fügen Sie eine/n Kund/in und seine/ihre Zahlungsmethode hinzu. Verwenden Sie in diesem Fall eine Testkarte.
Erstellen Sie ein Abonnement und fügen Sie einen kostenlosen Sieben-Tage-Testzeitraum hinzu:

So fügen Sie einem bestehenden Abonnement über das Dashboard einen Testzeitraum hinzu:

Suchen Sie das Abonnement, das Sie ändern möchten.

Klicken Sie auf Aktionen.
Klicken Sie auf Abonnement aktualisieren.
Klicken Sie auf Kostenlosen Testzeitraum hinzufügen und geben Sie im Feld Dauer des kostenlosen Testzeitraums die Zahl „Sieben“ ein.
Klicken Sie auf Abonnement aktualisieren.

Nachdem Sie ein Abonnement mit einem kostenlosen Sieben-Tage-Testzeitraum erstellt haben, wird ein Abonnement mit dem Status trialing erstellt. Aufgrund des kostenlosen Testzeitraums wird eine Rechnung mit dem Betrag 0,00 $ generiert.
Verschieben Sie das Datum auf den 5. Januar, um die Ereignisbenachrichtigung customer.subscription.trial_will_end anzuzeigen. Stripe sendet die Benachrichtigung drei Tage vor Ablauf des Testzeitraums. Mit diesem Webhook-Ereignis können Sie Ihre Kund/innen darüber informieren, dass der Testzeitraum in Kürze endet.
Verschieben Sie das Datum auf den 8. Januar. Sie können sehen, dass das Abonnement jetzt den Status paid hat und eine Rechnung über 50 USD erstellt wird.
Verschieben Sie das Datum um einen Zyklus (zum Beispiel auf den 8. Februar bei einem monatlichen Abonnement). Sie können sehen, dass das Abonnement erfolgreich verlängert wurde.

Einschränkungen

Um Test-Uhren sinnvoll vorzustellen, begrenzt Stripe die Komplexität jeder Simulation auf Folgendes:

Drei Kundinnen/Kunden
Drei Abonnements, einschließlich geplanter Abonnements, pro Kunde/Kundin
Zehn Angebote, die nicht mit Kundinnen/Kunden verknüpft sind

Test-Uhren-Objekte in Liste aller Ergebnisse ausgelassen

Stripe-Listen-APIs (wie Listen-Rechnungen) lassen von Test-Uhren generierte Ergebnisse für alle Listenanfragen. Um Ergebnisse anzuzeigen, die von Test-Uhren in diesen Fällen generiert werden, müssen Sie Ergebnisse innerhalb eines bestimmten übergeordneten Elements wie test_clock, customer oder subscription anfordern.

GET /v1/invoices gibt zum Beispiel keine von einer Test-Uhr generierten Rechnungen zurück, aber GET /v1/invoices/{customer_id} gibt alle Rechnungen für diesen Kunden/diese Kundin zurück, einschließlich derjenigen, die von der Test-Uhr generiert wurden.

Ebenso können Sie in diesem Beispiel eine Test-Uhr-ID angeben, um alle Rechnungen im Zusammenhang mit dieser Test-Uhr abzurufen, oder Sie können eine Abonnement-ID angeben, um alle Rechnungen zurückzugeben, die für dieses Abonnement in Rechnung gestellt wurden, einschließlich der von der Test-Uhr generierten Rechnungen.

Ratenbegrenzungsfehler

Wenn Sie mehrere Aktualisierungen an einem Abonnement vornehmen, das eine Test-Uhr hat, gibt Stripe möglicherweise einen Fehler bezüglich der Ratenbegrenzung zurück. Da das Abonnement auf die Zeit der Test-Uhr eingefroren ist, werden alle API-Anfragen auf diese Zeit angerechnet, was die Ratenbegrenzung auslösen kann.

Um dies zu vermeiden, stellen Sie die simulierte Uhrzeit der Uhr um einige Minuten vor, bevor Sie weitere API-Anfragen für das Abonnement stellen.

Ausnahmen bei der Zahlungsabwicklung

Beim Vorstellen der Test-Uhr wird der Einzug von Zahlungen durch Banklastschriften (z. B. die Zahlungsarten us_bank_account ) derzeit nicht unterstützt. Stripe zieht die Zahlungen ein, nachdem die Test-Uhr vorgestellt wurde. So testen Sie fehlgeschlagene Zahlungen:

Wählen Sie die Einstellung Abonnement kündigen, nachdem alle Zahlungsversuche fehlgeschlagen sind aus.
Fügen Sie Kundinnen/Kunden, die keine Zahlungen leisten, eine Zahlungsmethode vom Typ us_bank_account hinzu.
Legen Sie ein Abonnement für den Kunden/die Kundin.
Stellen Sie die Test-Uhr vor, um die Zahlung für ein Abonnement einzuziehen.

Nach dem Vorstellen der Test-Uhr bleibt das Abonnement im Zustand active. Dies bedeutet, dass während des Vorstellens der Test-Uhr kein Zahlungseinzug versucht wurde und das Abonnement aufgrund von payment_failed noch nicht in den Zustand canceled übergegangen ist.

Überwachen Sie das Ereignis invoice.payment_failed, um den verzögerten Abonnementstatus und die Rechnungszahlung zu überwachen. Das Ereignis customer.subscription.deleted zeigt an, dass der Abonnementstatus auf canceled gesetzt wurde.