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.

Standardmäßig treten Aktualisierungen unabhängig davon in Kraft, 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.

Vorsicht

Ausstehende Aktualisierungen werden nicht unterstützt, wenn die collection_method des Abonnements send_invoice lautet oder wenn als Zahlungsmethode für das Abonnement das Lastschriftverfahren verwendet wird.

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"
      }
    ]
  },
}

Fehlgeschlagene Zahlungen bearbeiten
Clientseitig

Überprüfen Sie nach der Aktualisierung den Hash pending_update für das Abonnement. Wenn Sie automatisch benachrichtigt werden möchten, können Sie einen Webhook erstellen, der auf das Ereignis customer.subscription.updated wartet. Wenn der Hash pending_update angegeben ist, war die Zahlung nicht erfolgreich und der Zyklus des Abonnements wird wie vor der Aktualisierung fortgesetzt.

Oftmals schlagen Zahlungen fehl, weil die Zahlungsmethode abgelehnt wird oder eine Kundenauthentifizierung erforderlich ist. Sie sollten eine Logik erstellen, um mit beiden Szenarien umgehen zu können.

Beachten Sie beim Umgang mit abgelehnten Kartenzahlungen die Anweisungen für Zahlungsfehlschläge. Weisen Sie der Kundin/dem Kunden eine neue Zahlungsmethode zu und verwenden Sie dann den Endpoint zum Bezahlen, um die im Zuge der Aktualisierung generierte Rechnung zu begleichen.

Beachten Sie die Anweisungen zu Kundenaktionen, um die Kundenauthentifizierung abzuwickeln. Die Kundenaktionen führen den/die Nutzer/in durch den Authentifizierungsprozess, um die Rechnung zu begleichen.

Bei einer erfolgreichen Zahlung:

Werden die Änderungen im Hash pending_update sofort angewendet.
Wird die Rechnung auf paid gesetzt.

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

OptionalAusstehende Aktualisierungen abbrechen oder ändern
Serverseitig

Siehe auch

Details zu Lebenszyklen, Webhooks und unterstützten Attributen bei der Verwendung von ausstehenden Aktualisierungen:

Dokumentation zu ausstehenden Aktualisierungen