Ausstehende Aktualisierungen

So gehen Sie bei der Aktualisierung von Abonnements mit fehlgeschlagenen Zahlungen um.

In folgenden Fällen wird beim Aktualisieren eines Abonnements eine neue Rechnung generiert:

Das Abonnement erfordert erstmalig eine Zahlung, beispielsweise nach Ablauf eines Testzeitraums.
Der Abrechnungszeitraum ändert sich.
Das Ändern des Abonnement führt zu einer anteilmäßigen Verrechnung und proration_behavior=always_invoice.

Viele Abo-Aktualisierungen generieren keine neuen Rechnungen oder lösen ausstehende Aktualisierungen aus, darunter:

Konfigurationsänderungen (Zahlungsmethoden, Steuereinstellungen, Einstellungen für erneute Versuche)
Metadatenaktualisierungen für Abonnement oder Abonnementposten
Angewandte Rabatte (auf zukünftige Rechnungen angewendet)
Anpassung des Abrechnungsschwellenwerts
cancel_at_period_end auf true setzen
Einmalige Zahlungen mit add_invoice_items hinzufügen

Diese Aktualisierungen gelten sofort ohne Auswirkungen auf die Zahlung. Eine vollständige Liste finden Sie unter Was keine anteilmäßige Verrechnungen auslöst.

Standardmäßig führt Stripe Aktualisierungen unabhängig davon durch, ob die Zahlung für die neue Rechnung erfolgreich ist. Wenn die Zahlung fehlschlägt, müssen die Aktualisierungen manuell zurückgesetzt werden. Sie müssen eine neue Rechnung erstellen, die Rechnungsposten anteilmäßig verrechnen und dann die Zahlung erneut veranlassen. Mit der Funktion für ausstehende Aktualisierungen können Sie allerdings nur dann Änderungen an Abonnements vornehmen, wenn die Zahlung für die neue Rechnung erfolgreich ist.

Bevor Sie loslegen

Sie können ausstehende Aktualisierungen verwenden, wenn die collection_method des Abonnements charge_automatically lautet und wenn die Zahlung des Abonnements entweder über eine Karte oder Link erfolgt.

Abonnement aktualisieren
Serverseitig

Sie können ausstehende Aktualisierungen mit den Aufrufen Abonnement aktualisieren, Abonnement-Artikel erstellen und Abonnement-Artikel aktualisieren 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.

Wenn die Zahlung erfolgreich ist, wird das Abonnement aktualisiert. Schlägt sie fehl, enthält das zurückgegebene Objekt Subscription den Hash pending_update mit den Änderungen:

{
  "id": "sub_49ty4767H20z6a",
  "object": "subscription",
  "application_fee_percent": null,
  "pending_update": {
    "expires_at": 1571194285,
    "subscription_items": [
      {
        "id": "si_09IkI4u3ZypJUk5onGUZpe8O",
        "price": "price_CBb6IXqvTLXp3f"
      }
    ]
  },
}

Umgang mit fehlgeschlagenen Zahlungen
Clientseitig

Überprüfen Sie nach der Aktualisierung den pending_update-Hash des Abonnements oder überwachen Sie das Ereignis customer.subscription.updated in Ihrem Webhook. Ein ausgefüllter pending_update-Hash bedeutet, dass die Zahlung fehlgeschlagen ist und Ihre Abonnementaktualisierung nicht angewendet wird.

Erstellen Sie eine Logik für den Umgang mit fehlgeschlagenen Zahlungen aufgrund von abgelehnten Karten und Anfragen zur Kundenauthentifizierung:

Bei Kartenablehnungen weisen Sie der Kundin/dem Kunden eine neue Zahlungsmethode zu. Verwenden Sie dann den Endpoint zum Bezahlen, um die bei der Aktualisierung generierte Rechnung zu bezahlen.
Befolgen Sie für die Kundenauthentifizierung den Ablauf Aktion erforderlich.

Bei erfolgreicher Zahlung werden die Änderungen im Hash pending_update sofort übernommen und der Status der Rechnung auf paid aktualisiert.

Wenn die Zahlung erneut fehlschlägt, bleibt der pending_update-Hash für das Abonnement beim ursprünglichen Ablaufdatum und es werden keine Änderungen angewendet.

OptionalAusstehende Aktualisierungen abbrechen oder ändern
Serverseitig

Wenn Sie eine ausstehende Aktualisierung abbrechen möchten, müssen Sie die im Zuge der Aktualisierung generierte Rechnung stornieren. Die Rechnungs-ID finden Sie im Attribut latest invoice des Abonnements. Verwenden Sie diese ID, um die Rechnung zu stornieren.

Sie können ein Abo mit neuen Werten für ein ausstehendes Update aktualisieren. Dadurch werden die Werte im Hash pending_update aktualisiert, die mit der vorherigen ausstehenden Aktualisierung verbundene Rechnung storniert und eine neue Rechnung erstellt, die die aktualisierten Werte berücksichtigt. Bei erfolgreicher Zahlung dieser neuen Rechnung werden die neuesten Aktualisierungen auf das Abo angewendet. Wenn die Zahlung fehlschlägt, wird eine neue ausstehende Aktualisierung mit einem neuen Ablaufdatum erstellt, die die bestehende ersetzt.

Unterstützte Attribute für ausstehende Aktualisierungen

Ausstehende Aktualisierungen unterstützen nur Attribute, die das Verhalten bei der anteilmäßigen Verrechnung steuern oder neue Rechnungen generieren.

Der Endpoint zur Aktualisierung eines Abonnements unterstützt die folgenden Attribute:

expand
payment_behavior
proration_behavior
proration_date
billing_cycle_anchor
items
- price
- quantity
trial_end
trial_from_plan
add_invoice_items

Die Endpoints zum Erstellen eines Abonnement-Eintrags und zur Aktualisierung eines Abonnement-Eintrags unterstützen die folgenden Attribute:

expand
payment_behavior
proration_behavior
proration_date
price
quantity

Abgelaufene Updates

Wenn Sie nach einer fehlgeschlagenen Aktualisierung nichts unternehmen, storniert Stripe die Rechnung und verwirft die Aktualisierung nach deren Ablauf.

Der expired_at-Zeitpunkt einer ausstehenden Aktualisierung stimmt mit dem ersten Vorkommen entweder des Endes des Testzeitraums oder des frühesten Endes des items.current-Zeitraums überein. Dies gilt, wenn einer der beiden Zeitpunkte innerhalb von 23 Stunden nach der Aktualisierungsanfrage liegt. Andernfalls beträgt die Ablauffrist 23 Stunden nach der Aktualisierungsanfrage.

Stripe storniert außerdem automatisch die Rechnung und entfernt die ausstehende Aktualisierung, wenn Folgendes geschieht:

Das Abrechnungslimit des Abonnements ist erreicht.
Ein mit dem Abonnement verknüpfter Abonnementplan geht in eine neue Phase über.

Ereignisse im Zusammenhang mit ausstehenden Aktualisierungen

Verwenden Sie Webhooks, um die folgenden Ereignisse im Zusammenhang mit ausstehenden Aktualisierungen zu überwachen:

Ereignis	Zweck
`customer.subscription.updated`	Empfangen von Benachrichtigungen für Abonnements, Prüfen auf den Hash `pending_updates` und Beheben von fehlgeschlagenen Zahlungen, falls erforderlich.
`customer.subscription.pending_update_applied`	Empfang von Benachrichtigungen, wenn ausstehende Aktualisierungen angewendet werden, sodass Sie weitere Maßnahmen ergreifen können, wie beispielsweise Upgrades, Downgrades, Bereitstellung oder Aufhebung der Bereitstellung von Dienstleistungen.
`customer.subscription.pending_update_expired`	Empfang von Benachrichtigungen, wenn ausstehende Aktualisierungen ablaufen oder automatisch storniert werden, und bei Bedarf erneute Durchführung der Aktualisierungsanfrage

Ausstehende Aktualisierungen und Abonnementpläne

Sie können sowohl ausstehende Aktualisierungen als auch Abonnementpläne verwenden, um Abonnements zu verwalten. Durch eine Änderung der Zeitplanphase wird eine ausstehende Aktualisierung verworfen und die zugehörige Rechnung wird storniert. Wiederholen Sie die Aktualisierungsanfrage nach dem Phasenwechsel, falls erforderlich.

Nutzungsbasierte Artikel

Wenn ein Abonnement nutzungsbasierte Artikel enthält, rechnet Stripe jede ausstehende Nutzung auf der Rechnung für die ausstehende Aktualisierung ab. Wenn die ausstehende Aktualisierung jedoch vor der Zahlung abläuft, verwirft Stripe diese Nutzung. Dadurch wird verhindert, dass sie in nachfolgenden Rechnungen abgerechnet wird.

Wenn durch die ausstehende Aktualisierung ein nutzungsbasierter Preis entfernt wird, ignoriert Stripe jegliche zwischen der Erstellung der ausstehenden Aktualisierung und der daraus resultierenden Rechnungszahlung gemeldete Nutzung. Diese Nutzung kann nicht in Rechnung gestellt werden. Wenn das Abonnement jedoch billing_mode=flexible beinhaltet, wird Stripe die Nutzung in Rechnung gestellt, wenn ein nutzungsbasierter Preis entfernt wird.