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.](https://b.stripecdn.com/docs-statics-srv/assets/test-clock-lifecycle.b711b9cf4feb52351e27958b8b924cb3.png)
Lebenszyklus der Test-Uhr
Folgen Sie dieser Anleitung, um mit der Verwendung von Test-Uhren zu beginnen:
- Test-Uhr löschen
- 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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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.
Ihre Simulation einrichten![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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.
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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.
Änderungen überwachen und verarbeiten![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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_ | Das Vorstellen der Uhr hat begonnen, die angegebene Zeit wurde aber noch nicht erreicht. |
test_ | 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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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.
Durch das Löschen der Uhr werden auch die mit der Uhr verknüpften Testkundinnen und -kunden gelöscht und ihre Abonnements storniert. Test-Uhren sind nur im Test-Modus verfügbar. Sie können also keine Produktionsobjekte löschen, wenn Sie eine Uhr löschen.
Use Cases![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Abonnementverlängerungen testen![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Führen Sie zunächst die folgenden Schritte aus, um mit der Verwendung von Test-Uhren zu beginnen:
- Test-Uhr löschen
- 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_
auf den 1. Januar fest.time - Fügen Sie einen Kunden/eine Kundin hinzu und fügen Sie eine Zahlungsmethode für den Kunden/die Kundin hinzu:
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Führen Sie zunächst die folgenden Schritte aus, um mit der Verwendung von Test-Uhren zu beginnen:
- Test-Uhr löschen
- 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_
auf den 1. Januar fest.time - 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:
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 Statusdraft
angezeigt.Um die Rechnung zu finalisieren, stellen Sie die Zeit um eine Stunde vor.
Testzeiträume![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Führen Sie zunächst die folgenden Schritte aus, um mit der Verwendung von Test-Uhren zu beginnen:
- Test-Uhr erstellen
- Testsimulation einrichten
- Die Uhrzeit vorstellen
- Änderungen überwachen und verarbeiten
- Simulation aktualisieren
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_
auf den 1. Januar fest.time - 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:
- 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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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_
, customer
oder subscription
anfordern.
GET /v1/invoices
gibt zum Beispiel keine von einer Test-Uhr generierten Rechnungen zurück, aber GET /v1/invoices/{customer_
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.
Ausnahmen bei der Zahlungsabwicklung![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Beim Vorstellen der Test-Uhr wird der Einzug von Zahlungen durch Banklastschriften (z. B. die Zahlungsarten us_
) 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_
hinzu.bank_ account 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_
noch nicht in den Zustand canceled
übergegangen ist.
Überwachen Sie das Ereignis invoice.
, um den verzögerten Abonnementstatus und die Rechnungszahlung zu überwachen. Das Ereignis customer.
zeigt an, dass der Abonnementstatus auf canceled
gesetzt wurde.