# Ausstehende Aktualisierungen So gehen Sie bei der Aktualisierung von Abonnements mit fehlgeschlagenen Zahlungen um. In folgenden Fällen wird beim Aktualisieren eines *Abonnement* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)s eine neue *Rechnung* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) 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 - Hinzufügen oder Aktualisieren von Gutscheinen oder Aktionscodes, die für zukünftige Rechnungen gelten - 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](https://docs.stripe.com/billing/subscriptions/prorations.md#no-prorations). 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. ## Before you begin Sie können ausstehende Aktualisierungen verwenden, wenn die [collection_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) des Abonnements `charge_automatically` ist und die Zahlungsmethode eine der folgenden ist: - [Karte](https://docs.stripe.com/payments/cards.md) - [Link](https://docs.stripe.com/payments/link.md) - [Alipay](https://docs.stripe.com/payments/alipay.md) - [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md) - [Afterpay/Clearpay](https://docs.stripe.com/payments/afterpay-clearpay.md) - [Apple Pay](https://docs.stripe.com/apple-pay.md) - [Cash App Pay](https://docs.stripe.com/payments/cash-app-pay.md) - [EPS](https://docs.stripe.com/payments/eps.md) - [GoPay](https://docs.stripe.com/payments/gopay.md) - [Google Pay](https://docs.stripe.com/google-pay.md) - [Kakao Pay](https://docs.stripe.com/payments/kakao-pay/accept-a-payment.md) - [Klarna](https://docs.stripe.com/payments/klarna.md) - [KR-Karte](https://docs.stripe.com/payments/kr-card/accept-a-payment.md) - [Naver Pay](https://docs.stripe.com/payments/naver-pay/accept-a-payment.md) - [NG Card](https://docs.stripe.com/payments/ng-card/accept-a-payment.md) - [PayPal](https://docs.stripe.com/payments/paypal.md) - [PayTo](https://docs.stripe.com/payments/payto.md) - [Pix](https://docs.stripe.com/payments/pix.md) - [PromptPay](https://docs.stripe.com/payments/promptpay.md) - [Revolut Pay](https://docs.stripe.com/payments/revolut-pay.md) - [Satispay](https://docs.stripe.com/payments/satispay.md) - [Stablecoins und Krypto](https://docs.stripe.com/payments/stablecoin-payments.md) - [Swish](https://docs.stripe.com/payments/swish.md) - [TWINT](https://docs.stripe.com/payments/twint.md) - [UPI](https://docs.stripe.com/payments/upi.md) - [WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) ## Abonnement aktualisieren [Serverseitig] 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" ``` 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: ```json { "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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). 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](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method) zu. Verwenden Sie dann den Endpoint zum [Bezahlen](https://docs.stripe.com/api/invoices/pay.md), um die bei der Aktualisierung generierte Rechnung zu bezahlen. - Befolgen Sie für die Kundenauthentifizierung den Ablauf [Aktion erforderlich](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). 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](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) und es werden keine Änderungen angewendet. ## Optional: Ausstehende 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](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-latest_invoice) des Abonnements. Verwenden Sie diese ID, um die Rechnung zu [stornieren](https://docs.stripe.com/api/invoices/void.md). Sie können [ein Abo mit neuen Werten für ein ausstehendes Update aktualisieren](https://docs.stripe.com/billing/subscriptions/pending-updates.md#update-subscription). 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](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) 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](https://docs.stripe.com/api/subscriptions/update.md) 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](https://docs.stripe.com/api/subscription_items/create.md) und zur [Aktualisierung eines Abonnement-Eintrags](https://docs.stripe.com/api/subscription_items/update.md) 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](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_end) oder des frühesten [Endes des items.current-Zeitraums](https://docs.stripe.com/api/subscriptions/object.md##subscription_object-items-data-current_period_end) ü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](https://docs.stripe.com/webhooks.md), um die folgenden Ereignisse im Zusammenhang mit ausstehenden Aktualisierungen zu überwachen. Die Ereignisse sind identisch, unabhängig davon, ob Sie `Customer`-Objekte oder kundenspezifisch konfigurierte `Account`-Objekte verwenden. | Ereignis | Zweck | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.updated` | Empfangen von Benachrichtigungen für Abonnements, Prüfen auf den Hash `pending_updates` und [Beheben von fehlgeschlagenen Zahlungen](https://docs.stripe.com/billing/subscriptions/pending-updates.md#handling-failed-payments), 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) 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.