# 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 Simulation getrennt von einem Abonnement erstellen, um erweiterte Simulationen auszuführen. In diesem Szenario erstellen Sie zuerst die Simulation und fügen dann verschiedene Testfälle hinzu. Sie sind noch nicht bereit für eine vollständige Integration? Sehen Sie [sich unseren Leitfaden](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md) zum Ausführen von Simulationen für Abonnements an. Folgen Sie dieser Anleitung, um mit der Verwendung von Test-Uhren zu beginnen: 1. [Eine Simulation erstellen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [Ihre Simulation einrichten](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [Die Zeit vorstellen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [Änderungen überwachen und handhaben](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [Simulation aktualisieren](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) 1. [Die Simulation löschen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#delete-clock) Sie können die Zeit vorstellen, Änderungen überwachen und die Simulation so oft wie nötig aktualisieren, um verschiedene Fälle zu testen. ## Simulation erstellen und Uhrzeit festlegen Bei einer Simulation wird eine Uhr als Objekt verwendet, sodass Sie sich auf die Zeit dieser Uhr beziehen können. Um eine Simulation zu starten, erstellen Sie eine Uhr und stellen Sie deren fixierte Zeit ein – den Ausgangspunkt für Ihre Tests. Stellen Sie die fixierte Zeit auf einen Punkt in der Vergangenheit oder in der Zukunft ein. Nachdem Sie sie eingestellt haben, können Sie sie jedoch nur in der Zeit voran gehen. #### Dashboard [Erstellen Sie eine Sandbox](https://docs.stripe.com/sandboxes/dashboard/manage.md), um mit der Simulation zu beginnen. 1. Gehen Sie zum [Abschnitt **Abonnements**](https://dashboard.stripe.com/test/subscriptions) unter der Registerkarte **Abrechnung**. 1. Klicken Sie im Banner auf den Link [Simulationen](https://dashboard.stripe.com/test/test-clocks). 1. Klicken Sie auf **Neue Simulation**. 1. 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`. 1. Legen Sie die fixierte Zeit für die Simulation fest. #### API Bei Verwendung der API geben Sie die Zeit im Feld [frozen_time](https://docs.stripe.com/api/test_clocks/object.md#test_clock_object-frozen_time) als Unix-Epoch-Zeitstempel an. In diesem Beispiel wird der bestimmte Zeitpunkt der Uhr `Annual renewal` auf 1. November 2021 7:00:00 GMT (`1635750000` in Unix-Epoch-Format) festgelegt. ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks \ -u "<>:" \ -d frozen_time=1635750000 \ -d "name=Annual renewal" ``` Notieren Sie die `id` der erstellten Test-Uhr (zum Beispiel `clock_1JGWQvIyEfDZOm8cxyhPwsoc`). Sie verwenden die ID, um einen Kunden/eine Kundin zu erstellen und um die Zeit vorzustellen. ## 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. #### Dashboard So erstellen Sie einen Kunden/eine Kundin für Ihre Simulation über das Dashboard: 1. Gehen Sie zur Seite [Simulationen](https://dashboard.stripe.com/test/test-clocks) und suchen Sie Ihre Simulation. 1. Klicken Sie auf **Hinzufügen** > **Kunden/Kundin hinzufügen**. Bei der Simulation können Sie keine bestehenden Kundinnen und 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: 1. Gehen Sie zur Seite [Simulationen](https://dashboard.stripe.com/test/test-clocks) und suchen Sie die Simulation. 1. 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. 1. Wählen Sie im Abschnitt **Preisinformationen** ein wiederkehrendes Produkt und einen Preis aus. 1. Definieren Sie für den **Abonnementplan** das Start- und Enddatum für das Abo und den Beginn des Rechnungsstellungszeitraums. 1. Wählen Sie eine Zahlungseinzugsmethode aus: - Wählen Sie **Zahlungsmethode automatisch belasten**, wenn Sie die Kundin/den Kunden zu Beginn des Rechnungsstellungszeitraums 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. 1. Klicken Sie auf **Test-Abo starten**, um das Abo und den Rechnungsstellungszeitraum zu starten. #### API > #### Verwenden Sie die Accounts v2 API zum Darstellen von Kundinnen und Kunden > > Die Accounts v2 API ist für Connect-Nutzer/innen allgemein verfügbar und befindet sich für andere Stripe-Nutzer/innen in der öffentlichen Vorschau. Alle Stripe-Nutzer/innen können Accounts v2 [in ihrem Dashboard](https://dashboard.stripe.com/settings/connect/platform-setup) aktivieren. Nutzer/innen der Vorschau müssen bei Aufrufen der Accounts v2 API jedoch [eine Vorschauversion angeben](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning). > > Für die meisten Anwendungsfälle empfehlen wir, [Ihre Kundinnen und Kunden als vom Kunden bzw. von der Kundin konfigurierte Account-Objekte abzubilden](https://docs.stripe.com/connect/use-accounts-as-customers.md), anstatt das [Kundenobjekt](https://docs.stripe.com/api/customers.md) zu verwenden. Verwenden Sie das folgende Codebeispiel, um einen Kunden/eine Kundin zu erstellen und ihn/sie mit der Uhr zu verknüpfen. Legen Sie unbedingt eine Standard-Zahlungsmethode für den Kunden/die Kundin fest (es sei denn, Sie möchten einen kostenlosen Testzeitraum oder eine ähnliche Simulation testen). Hierfür können Sie eine [Testkarte](https://docs.stripe.com/testing.md#cards) verwenden. #### Accounts v2 Um ein kundenkonfiguriertes `Account` mit einer standardmäßigen Zahlungsmethode zu erstellen, müssen Sie zunächst das `Account` erstellen und dann die Zahlungsmethode dem `Account` zuordnen. Beim Erstellen eines `Account`s können Sie keine Standardzahlungsmethode angeben. Um ein v2 `Account` mit einer Test-Uhr zu verwenden, müssen Sie die Test-Uhr-ID festlegen, wenn Sie die `customer`-Konfiguration zum ersten Mal zum `Account` hinzufügen. Sie können die Konfiguration hinzufügen, wenn Sie das `Account` erstellen oder aktualisieren, aber Sie können sie nicht hinzufügen und die Test-Uhr-ID später festlegen. Um ein `PaymentMethod`-Objekt zu generieren und es dem `Account` zuzuordnen, verwenden Sie die Angaben zur Zahlungsmethode, um einen [SetupIntent](https://docs.stripe.com/api/setup_intents/create.md) oder [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) zu erstellen, und geben Sie die `Account`-ID als Parameter `customer_account` an: ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d confirm=true \ -d customer_account=acct_1234 \ -d "mandate_data[customer_acceptance][accepted_at]=1678942624" \ -d "mandate_data[customer_acceptance][type]=offline" \ -d "payment_method_data[billing_details][address][line1]=234 Oak Street" \ -d "payment_method_data[billing_details][address][postal_code]=12345" \ --data-urlencode "payment_method_data[billing_details][email]=jenny.rosen@example.com" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][account_holder_type]=individual" \ --data-urlencode "payment_method_data[us_bank_account][account_number]=********6789" \ -d "payment_method_data[us_bank_account][routing_number]=110000000" \ -d "payment_method_options[us_bank_account][verification_method]=automatic" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://www.stripe.com" ``` Der zurückgegebene `SetupIntent` oder `PaymentIntent` enthält die ID des generierten `PaymentMethod`-Objekts in seiner Eigenschaft [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method). Aktualisieren Sie als Nächstes das kundenkonfigurierte `Account` und geben Sie die `PaymentMethod`-ID als Parameter [default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-configuration-customer-billing-default_payment_method) an: ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "billing": { "default_payment_method": "pm_1234" } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 [Erstellen Sie eine Kundin/einen Kunden](https://docs.stripe.com/api/customers/create.md), legen Sie den Parameter `test_clock` auf die Test-Uhr-ID fest und setzen Sie die Parameter `payment_method` und `rechnung_settings.default_zahlung_method` auf die ID der `PaymentMethod`: ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_1234 \ -d "invoice_settings[default_payment_method]=pm_1234" ``` Der Endpoint [Alle Kundinnen und Kunden auflisten](https://docs.stripe.com/api/customers/list.md) gibt keine Kundinnen und Kunden zurück, die mit Test-Uhren verknüpft sind, es sei denn, Sie geben im Parameter [test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock) eine Test-Uhr-ID an. Verwenden Sie den/die von Ihnen erstellten Kunden/von Ihnen erstellte Kundin, um ein [neues Abonnement zu erstellen](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). Das Abonnement wird über den Kunden/die Kundin mit der Uhr verknüpft. Sie müssen also die ID der Uhr nicht übergeben, um das Abonnement zu erstellen. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{RECURRING_PRICE_ID}}" ``` Sowohl die Kundin/der Kunde als auch das Abonnement sind mit der im [ersten Schritt](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) erstellten Simulation verknüpft. ## Simulierte Zeit vorstellen Nachdem Sie eine Simulation erstellt und Ihren Testfall eingerichtet haben, stellen Sie die simulierte Zeit vor. Wenn Sie dies zum ersten Mal tun, stellen Sie die Zeit ab der anfänglich fixierten Zeit vor, die Sie zu Beginn festgelegt haben. 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 Abo). Stellen Sie die Zeit um jeweils bis zu zwei Intervalle vor. Die Länge des Intervalls richtet sich nach dem kürzesten mit dem Abonnement verknüpften Leistungszeitraum, der durch den wiederkehrenden Preis bestimmt wird. Wenn Sie beispielsweise ein monatliches Abonnement haben, können Sie die Zeit jeweils nur um bis zu zwei Monate vorstellen. Wenn Sie keine Abonnements oder Abonnementpläne eingerichtet haben, können Sie sie bis zu zwei Jahre ab der ursprünglich fixierten Zeit vorstellen. #### Dashboard So stellen Sie die Zeit über das Dashboard vor: 1. Gehen Sie zur Seite [Simulationen](https://dashboard.stripe.com/test/test-clocks) und suchen Sie Ihre Simulation. 1. Klicken Sie auf **Vorlaufzeit**. 1. Verwenden Sie das Kalender-Modal, um das Datum auszuwählen, auf das Sie die Uhr vorstellen möchten. 1. Klicken Sie auf **Vorlauf**. #### API Um die Zeit über die API vorzustellen, aktualisieren Sie den Parameter `frozen_time`. So stellen Sie die Zeit beispielsweise auf den 1. November 2022 vor, um eine jährliche Verlängerung zu testen: ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}}/advance \ -u "<>:" \ -d frozen_time=1667286000 ``` ## Änderungen überwachen und verarbeiten Nach einer erfolgreichen API Anfrage oder einem Dashboard-Vorgang dauert es ein paar Sekunden, die Zeit auf die spezifizierte Zeit vorzustellen. Um zu erfahren, wann sich der Status der Simulation geändert hat, können Sie Webhooks verwenden, um Ereignisbenachrichtigungen zu überwachen. Alternativ können Sie das Uhr-Objekt abfragen. Das Dashboard spiegelt auch die Änderungen wider. Sie können beispielsweise auf der [Seite „Rechnungen“](https://dashboard.stripe.com/test/invoices) überprüfen, ob eine Rechnung für Ihr Abonnement erstellt oder bezahlt wurde. Wenn Sie [Webhooks](https://docs.stripe.com/webhooks.md) 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](https://docs.stripe.com/billing/subscriptions/webhooks.md) 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, [rufen Sie](https://docs.stripe.com/api/test_clocks/retrieve.md) sie anhand der ID ab, um ihren `status` zu überprüfen. ```curl curl https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` ## Simulation aktualisieren Für Simulationen wie die Folgenden können Sie weiterhin Änderungen vornehmen und [die Uhr vorstellen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock): - Hinzufügen eines [Kundensaldos](https://docs.stripe.com/billing/customer/balance.md). - Upgrades in der Mitte eines Zyklus durchführen. - [Einmalige Rechnungsposten hinzufügen](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items). [Überwachen Sie die Änderungen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) nach jedem Update erneut. Wiederholen Sie diesen Vorgang so oft wie nötig, um die Anforderungen Ihres Testfalls zu erfüllen. ## Eine Simulation löschen Simulationen 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. #### Dashboard So löschen Sie eine Simulation und alle zugehörigen Testobjekte über das Dashboard: 1. Gehen Sie zur Seite [Simulationen](https://dashboard.stripe.com/test/test-clocks) und suchen Sie Ihre Simulation. 1. Klicken Sie auf **Simulation abschließen**. 1. Klicken Sie im Bestätigungs-Modal auf **Abschließen**. #### API So löschen Sie die Uhr und alle zugehörigen Testobjekte über die API: ```curl curl -X DELETE https://api.stripe.com/v1/test_helpers/test_clocks/{{CLOCK_ID}} \ -u "<>:" ``` Durch das Löschen der Simulation werden auch die mit der Uhr verknüpften Testkundinnen und -kunden gelöscht und ihre Abonnements storniert. Simulationen sind nur in Sandboxes verfügbar. Sie können also keine Produktionsobjekte löschen, wenn Sie eine Uhr löschen. ## Anwendungsfälle Beginnen Sie in jedem Fall mit der Erstellung einer neuen Simulation: 1. [Eine Simulation erstellen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#create-clock) 1. [Ihre Simulation einrichten](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#setup-simulation) 1. [Die Zeit vorstellen](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#advance-clock) 1. [Änderungen überwachen und handhaben](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#monitor-changes) 1. [Simulation aktualisieren](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#update-simulation) ### Abonnementverlängerungen testen Nehmen wir an, Sie möchten testen, ob ein 50 USD/-monatliches Abonnement korrekt verlängert wird: - Erstellen Sie eine Simulation und legen Sie deren `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: #### Dashboard So fügen Sie eine Zahlungsmethode für einen Kunden/eine Kundin im Dashboard hinzu: 1. Klicken Sie auf der Kontoseite des Kunden/der Kundin im Abschnitt **Zahlungsmethoden** auf **Hinzufügen > Karte hinzufügen**. 1. Geben Sie Zahlungsinformationen ein. Verwenden Sie in diesem Fall die 4242424242424242 [Testkarte](https://docs.stripe.com/testing.md#cards). 1. Klicken Sie im Modal auf **Karte hinzufügen**. #### API #### Accounts v2 Um ein kundenkonfiguriertes `Account` mit einer standardmäßigen Zahlungsmethode zu erstellen, müssen Sie zunächst das `Account` erstellen und dann die Zahlungsmethode dem `Account` zuordnen. Beim Erstellen eines `Account`s können Sie keine Standardzahlungsmethode angeben. Um ein v2 `Account` mit einer Test-Uhr zu verwenden, müssen Sie die Test-Uhr-ID festlegen, wenn Sie die `customer`-Konfiguration zum ersten Mal zum `Account` hinzufügen. Sie können die Konfiguration hinzufügen, wenn Sie das `Account` erstellen oder aktualisieren, aber Sie können sie nicht hinzufügen und die Test-Uhr-ID später festlegen. Um ein `PaymentMethod`-Objekt zu generieren und es dem `Account` zuzuordnen, verwenden Sie die Angaben zur Zahlungsmethode, um einen [SetupIntent](https://docs.stripe.com/api/setup_intents/create.md) oder [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md) zu erstellen, und geben Sie die `Account`-ID als Parameter `customer_account` an: ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d confirm=true \ -d customer_account=acct_1234 \ -d "mandate_data[customer_acceptance][accepted_at]=1678942624" \ -d "mandate_data[customer_acceptance][type]=offline" \ -d "payment_method_data[billing_details][address][line1]=234 Oak Street" \ -d "payment_method_data[billing_details][address][postal_code]=12345" \ --data-urlencode "payment_method_data[billing_details][email]=jenny.rosen@example.com" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][account_holder_type]=individual" \ --data-urlencode "payment_method_data[us_bank_account][account_number]=********6789" \ -d "payment_method_data[us_bank_account][routing_number]=110000000" \ -d "payment_method_options[us_bank_account][verification_method]=automatic" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://www.stripe.com" ``` Der zurückgegebene `SetupIntent` oder `PaymentIntent` enthält die ID des generierten `PaymentMethod`-Objekts in seiner Eigenschaft [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method). Aktualisieren Sie als Nächstes das kundenkonfigurierte `Account` und geben Sie die `PaymentMethod`-ID als Parameter [default_payment_method](https://docs.stripe.com/api/v2/core/accounts/update.md#v2_update_accounts-configuration-customer-billing-default_payment_method) an: ```curl curl -X POST https://api.stripe.com/v2/core/accounts/acct_1234 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-03-25.preview" \ --json '{ "configuration": { "customer": { "billing": { "default_payment_method": "pm_1234" } } }, "include": [ "configuration.customer" ] }' ``` #### Customers v1 [Erstellen Sie eine Kundin/einen Kunden](https://docs.stripe.com/api/customers/create.md), legen Sie den Parameter `test_clock` auf die Test-Uhr-ID fest und setzen Sie die Parameter `payment_method` und `rechnung_settings.default_zahlung_method` auf die ID der `PaymentMethod`: ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ --data-urlencode "email=jenny.rosen@example.com" \ -d test_clock={{CLOCK_ID}} \ -d payment_method=pm_1234 \ -d "invoice_settings[default_payment_method]=pm_1234" ``` Der Endpoint [Alle Kundinnen und Kunden auflisten](https://docs.stripe.com/api/customers/list.md) gibt keine Kundinnen und Kunden zurück, die mit Test-Uhren verknüpft sind, es sei denn, Sie geben im Parameter [test_clock](https://docs.stripe.com/api/customers/list.md#list_customers-test_clock) eine Test-Uhr-ID an. - 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 nach vorne auf den 1. Februar, um zu sehen, dass eine Rechnung in Höhe von erstellt wird. Standardmäßig erscheint die Rechnung in einem `draft`-Status für [eine Stunde](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items). - 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 Angenommen, Sie haben zwei Produkte. Ein Produkt kostet 50 USD pro Monat (Basisplan) und das andere /Monat (Premiumplan). In diesem Fall möchten Sie vielleicht die anteilsmäßige Verrechnung für eine Kundin/einen Kunden testen, die/der in der Mitte eines Rechnungsstellungszeitraums von einem Basisplan zu einem Premiumplan wechselt. So simulieren Sie diese Situation: - Erstellen Sie eine Simulation und legen Sie die `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 4242424242424242 [Testkarte](https://docs.stripe.com/testing.md#cards). - 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: #### Dashboard So führen Sie ein Upgrade eines Abonnements über das Dashboard durch: 1. Klicken Sie auf der Kundenkontoseite oder der Seite mit den Abonnementdetails auf das Überlaufmenü eines Abonnements (⋯) und wählen Sie dann **Abo aktualisieren** aus. 1. Nehmen Sie Ihre gewünschten Änderungen vor. 1. Klicken Sie oben rechts auf **Abonnement aktualisieren**, um die Änderungen zu übernehmen. #### API Sie können ausstehende Aktualisierungen mit den Aufrufen [Abonnement aktualisieren](https://docs.stripe.com/api/subscriptions/update.md), [Abonnement-Artikel erstellen](https://docs.stripe.com/api/subscription_items/create.md) und [Abonnement-Artikel aktualisieren](https://docs.stripe.com/api/subscription_items/update.md) verwenden. Wenn Sie die Aktualisierung vornehmen, legen Sie `payment_behavior=pending_if_incomplete` fest. Im folgenden Beispiel wird einem Abonnement ein neuer Preis hinzugefügt. Aufgrund von `proration_behavior=always_invoice` wird eine Rechnung erstellt und es erfolgt ein Zahlungsversuch, sobald die Aktualisierung vorgenommen wurde. #### Curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` - Nach der Aktualisierung des Abonnements wird das Webhook-Ereignis [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-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 zunächst im `draft`-Status angezeigt, wo sie für ca. [eine Stunde](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items) verbleibt. - Um die Rechnung zu finalisieren, stellen Sie die Zeit um eine Stunde vor. ### Testzeiträume Angenommen, Sie möchten, dass Ihre Kundinnen und Kunden 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 Simulation und legen Sie die `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 4242424242424242 [Testkarte](https://docs.stripe.com/testing.md#cards). - Erstellen Sie ein Abonnement und fügen Sie einen kostenlosen Sieben-Tage-Testzeitraum hinzu: #### Dashboard So fügen Sie einem bestehenden Abonnement über das Dashboard einen Testzeitraum hinzu: Suchen Sie das Abonnement, das Sie ändern möchten. 1. Klicken Sie auf **Aktionen**. 1. Klicken Sie auf **Abonnement aktualisieren**. 1. Klicken Sie auf **Kostenlosen Testzeitraum hinzufügen** und geben Sie im Feld **Dauer des kostenlosen Testzeitraums** die Zahl „Sieben“ ein. 1. Klicken Sie auf **Abonnement aktualisieren**. #### API Sie können das Abonnement eines/einer Kund/in mit einem kostenlosen Testzeitraum starten, indem Sie beim Erstellen des Abonnements das Argument `trial_period_days=7` angeben: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` - 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 USD generiert. - Verschieben Sie das Datum auf den 5. Januar, um die Ereignisbenachrichtigung [customer.subscription.trial_will_end](https://docs.stripe.com/api/events/types.md#event_types-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 Sie können Simulationen durchführen bis zu: - Drei Kundinnen/Kunden - Drei Abonnements, einschließlich [geplanter Abonnements](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md), pro Kunde/Kundin - Zehn Angebote, die nicht mit Kundinnen/Kunden verknüpft sind ### Test-Uhren-Objekte in Liste aller Ergebnisse ausgelassen API-Auflistungsmethoden (z. B. [Rechnungen auflisten](https://docs.stripe.com/api/invoices/list.md)) geben keine von Test-Uhren generierten Objekte zurück, es sei denn, Sie legen eine Abfrageklausel fest. Die erforderlichen Abfrageparameter variieren je nach Ressource, überprüfen Sie daher den spezifischen Eintrag zur Auflistungsmethode in der API-Dokumentation. `GET /v1/invoices` gibt beispielsweise keine von Test-Uhren generierten Rechnungen zurück, `GET /v1/invoices` mit einer Abfrageklausel wie `customer:"cus_123"` gibt jedoch alle Rechnungen für diesen Kunden/diese Kundin zurück, einschließlich derjenigen, die von Test-Uhren 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. Die Subscriptions API beschränkt die maximale Anzahl von Anfragen wie folgt: - 10 neue Rechnungen pro Abonnement pro Minute - 20 neue Rechnungen pro Abonnement pro Tag - 200 Mengenaktualisierungen pro Abonnement pro Stunde ### 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: 1. Wählen Sie die Einstellung **Abonnement kündigen, nachdem alle Zahlungsversuche fehlgeschlagen sind** aus. 1. Fügen Sie Kundinnen/Kunden, die keine Zahlungen leisten, eine Zahlungsmethode vom Typ `us_bank_account` hinzu. 1. Legen Sie ein Abonnement für den Kunden/die Kundin. 1. Stellen Sie die Test-Uhr vor, um die Zahlung für ein Abonnement einzuziehen. Nach der Vorwärtsbewegung der Test-Uhr bleibt das Abonnement im Status `active`. Dies bedeutet, dass der Einzug der Zahlung während des Fortlaufens der Test-Uhr nicht versucht wurde und das Abonnement nicht in den Status `canceled` aufgrund einer `payment_failed` übergegangen ist. Achten Sie per Listener auf das Ereignis `invoice.payment_failed`, um den verzögerten Status des Abonnements und der Zahlung der Rechnung zu überwachen. Das Ereignis `customer.subscription.deleted` zeigt an, dass der Status des Abonnements auf `canceled` gesetzt wurde.