Aktualisierungen der Invoices API
In früheren Versionen der Stripe-API hatten Rechnungen keinen Status. Stattdessen wurde eine Reihe von booleschen Werten wie closed
, paid
und forgiven
verwendet.
Die neuen Rechnungsstatus sollen helfen, Stripe-Rechnungen besser mit verschiedenen Finanzabläufen zu korrelieren. Künftig haben alle Invoice-Objekte eine status
-Eigenschaft. Das Feld status
kann die Werte draft
, open
, paid
, void
und uncollectible
aufweisen.
- Der Status
draft
gibt an, dass eine Rechnung noch verändert werden kann. - Der Status
open
gibt an, dass die Rechnung final ist, nicht mehr geändert werden kann und bereit für die Zahlung ist. - Der Status
paid
gibt an, dass die Rechnung vollständig bezahlt wurde. - Der Status
void
gibt an, dass die Rechnung nicht mehr gültig ist. - Der Status
uncollectible
gibt an, dass die Rechnung höchstwahrscheinlich nicht bezahlt wird und als Forderungsausfall betrachtet werden kann.
Weitere Einzelheiten zu diesen Status und ihren Übergängen finden Sie im Leitfaden zu Rechnungen guide.
Beispiele für den zeitlichen Ablauf der Rechnungsstellung
In diesem Abschnitt finden Sie Beispiele für den zeitlichen Ablauf von sowohl einmaligen als auch wiederkehrenden Rechnungen, zusammen mit den jeweiligen Status, die diese beiden Rechnungsarten zu verschiedenen Zeitpunkten haben können.
Beispiel einer einmaligen Rechnung
Hier ist ein Beispiel für den zeitlichen Ablauf einer einmaligen Rechnung. Diese Abfolge von Ereignissen hat sich kaum geändert. Neu ist im Grunde nur das Feld status
, mit dem Stripe den Status einer Rechnung genauer darstellt.
- 16. November: Sie erstellen über die API eine Rechnung für die Lieferung von 12 Widgets an einen Kunden. Stripe benachrichtigt Sie mit dem Webhook
invoice.created
über die kürzlich erstellte Rechnung. Wenn Sie den Vorgang in der API prüfen, sehen Sie, dass die Rechnung den Statusstatus='draft'
hat. - 26. November: Nach dem Prüfen wird die Rechnung von der Buchhaltung über das Stripe-Dashboard finalisiert. Ihr Status ändert sich dann in
status='open'
und das Feldfinalized_at
wird festgelegt. Stripe benachrichtigt Sie mit dem Webhookinvoice.finalized
darüber, dass die Rechnung jetzt final ist. - 26. November: Ein paar Sekunden später versendet Stripe die Rechnung per E-Mail und beginnt, die Zahlung einzuziehen. Damit Sie den Rechnungsversand in Ihrem CRM-System nachverfolgen können, übermittelt Stripe bei jedem Rechnungsversand den Webhook
invoice.sent
. - 1. Dezember: Ihre Kundin/Ihr Kunde klickt auf den Link in der E-Mail und bezahlt die Rechnung über eine gehostete Zahlungsseite. Leider wird dabei eine abgelaufene Kreditkarte verwendet. Die Zahlung schlägt fehl und Stripe benachrichtigt Sie mit dem Webhook
invoice.payment_failed
über dieses Ereignis. - 3. Dezember: Die Kundin/der Kunde unternimmt einen neuen Zahlungsversuch mit einer anderen Kreditkarte – diesmal mit Erfolg. Stripe benachrichtigt Sie mit dem Webhook
invoice.paid
über dieses Ereignis, speichert die Karte und legt den Status der Rechnung aufstatus='paid'
fest. Falls konfiguriert, sendet Stripe Ihrer Kundin/Ihrem Kunden auch direkt einen E-Mail-Beleg über die erfolgreiche Bezahlung der Rechnung.
Beispiel einer wiederkehrenden Rechnung
Hier ist ein Beispiel für den zeitlichen Ablauf einer durch ein Abonnement generierten (wiederkehrenden) Rechnung.
- 13. November: Sie erstellen über das Dashboard ein wiederkehrendes Abonnement für eine Kundin/einen Kunden und konfigurieren es für die automatische Abbuchung. Das Abonnement hat einen Testzeitraum von 20 Tagen, was bedeutet, dass die erste Rechnung in 20 Tagen (am 3. Dezember) versendet wird. Stripe übermittelt den Webhook
customer.subscription.created
.
- 30. November: Drei Tage bevor der Testzeitraum endet, übermittelt Stripe den Webhook
customer.subscription.trial_will_end
. Drei Tage vor dem Belasten der Kreditkarte ist ein guter zeitlicher Anhaltspunkt für den Versand einer entsprechenden Erinnerungs-E-Mail.
- 3. Dezember: Nach Ablauf des Testzeitraums wird eine Rechnung mit dem Status
status='draft'
erstellt. Stripe benachrichtigt Sie mit dem Webhookinvoice.created
über die kürzlich erstellte Rechnung. - 3. Dezember: Ungefähr eine Stunde später wird die Rechnung automatisch finalisiert. Dabei ändert Stripe den
status
in'open'
, legtfinalized_at
fest und übermittelt den Webhookinvoice.finalized
. - 3. Dezember: Kurz darauf versucht Stripe, die für die Kundin/den Kunden hinterlegte Karte zu belasten. Die Kundenzahlung ist erfolgreich. Stripe benachrichtigt Sie mit dem Webhook
invoice.paid
über dieses Ereignis und legt den Status der Rechnung aufstatus='paid'
fest.
Neue API-Methoden
Stripe hat eine Reihe neuer APIs zur Verwaltung des Status einer Rechnung entwickelt. Hier ist ein Überblick über die neuen Optionen, die in der Aktualisierungscheckliste näher beschrieben werden:
- Rechnung senden: Stripe versendet Rechnungen und Zahlungserinnerungen automatisch per E-Mail. Mit diesem Endpoint, der über die Stripe-API zur Verfügung steht, können Sie eine Rechnung zu einem beliebigen Zeitpunkt versenden.
- Rechnung finalisieren: In dem Beispiel oben hat die Buchhaltung die Rechnung über das Stripe-Dashboard finalisiert. Das gleiche ist aber auch über die Stripe-API möglich.
- Rechnung stornieren: Nachdem eine Rechnung final ist, kann sie nicht mehr gelöscht werden. Durch das Stornieren können Sie festhalten, dass die Rechnung irrtümlich erstellt wurde. So können Sie z. B. eine Rechnung mit falschem Firmennamen stornieren und dann durch eine komplett neue Rechnung ersetzen.
- Rechnungsentwurf löschen: Diese Aktion steht nur für Rechnungsentwürfe zur Verfügung. Gelöschte Rechnungen sind weder im Dashboard noch über die API sichtbar. Der Löschvorgang kann nicht rückgängig gemacht werden.
- Rechnung als uneinbringlich markieren: Ihre Buchhaltung kann bei Bedarf eine Liste mit “zweifelhaften Forderungen” führen, bei denen es sich um Zahlungsausfälle handelt. Sie können diese API verwenden, um entsprechende Rechnungen zu kennzeichnen.
Aktualisierungscheckliste
In den folgenden Abschnitten sind die funktionellen Änderungen am Invoice
-Objekt und an den rechnungsbezogenen Webhooks aufgeführt.
Invoice
-Objekt
Stripe hat dem Invoice
-Objekt mehrere Felder hinzugefügt, damit Nutzer/innen die einzelnen Status und Vorgänge besser nachvollziehen können.
finalized_at
Das neue Feld finalized_at
gibt den Zeitpunkt an, zu dem die Rechnung finalisiert wurde. Das betrifft Anforderungen in allen API-Versionen.
status
Das neue Feld status
steht für Anforderungen in allen API-Versionen zur Verfügung. Es ersetzt viele boolesche Werte in Rechnungen:
- Für Anforderungen mit der Version vom 08.11.2018 oder später wurde der boolesche Wert
paid=true
entfernt. Verwenden Sie stattdessen den Statusstatus='paid'
. - Für Anforderungen mit der Version vom 08.11.2018 oder später wurde der boolesche Wert
forgiven=true
entfernt. Verwenden Sie stattdessen den Statusstatus='uncollectible'
.
auto_advance
Das neue Feld auto_advance
gibt an, ob der automatische Zahlungseinzug aktiv ist. Bei den Status 'draft'
und 'open'
kann das Feld auto_advance
aktualisiert werden. Ansonsten ist auto_advance
immer false
.
Bei auto_advance=false
führt Stripe Folgendes nicht durch:
- Automatische Ausstellung von Rechnungsentwürfen
- Automatischer erster oder wiederholter Versand von Rechnungen mit
collection_method='send_invoice'
- Automatischer erster oder wiederholter Zahlungsversuch für Rechnungen mit
collection_method='charge_automatically'
Selbst bei auto_advance=false
gleicht Stripe eingehende Überweisungen automatisch ab. Wenn eine Überweisung auf eine Rechnung verweist, wird die Überweisung mit dieser Rechnung abgeglichen. Wird keine Rechnung bereitgestellt, sucht Stripe nach unbezahlten Rechnungen und unternimmt einen entsprechenden Zahlungsversuch.
Bei Rechnungen mit den Status 'uncollectible'
, 'void'
und 'paid'
ist das Feld auto_advance
immer false
.
In Versionen vor dem 08.11.2018 ist das Feld closed
noch vorhanden und entspricht dem Kehrwert von auto_advance
. So entspricht auto_advance=true
zum Beispiel closed=false
(und umgekehrt). Rechnungen, die mit früheren API-Versionen erstellt wurden, haben weiterhin den Standardwert closed=false
.
Webhooks
Mit diesem Update haben wir drei neue Webhooks eingeführt:
invoice.finalized
: Wird beim Finalisieren einer Rechnung übermittelt.invoice.voided
: Wird beim Stornieren einer Rechnung übermittelt.invoice.marked_uncollectible
: Wird beim Markieren einer Rechnung als uneinbringlich übermittelt.
Der bestehende Webhook invoice.created
wird beim Erstellen einer Rechnung übermittelt. Wenn Ihr Webhook-Handler zwischen einmaligen Rechnungen und durch ein Abonnement generierten Rechnungen unterscheiden muss, überprüfen Sie, ob im Hauptteil des Webhooks die Eigenschaft invoice.subscription
vorhanden ist.
An diesen bereits bestehenden Webhooks hat sich nichts geändert:
invoice.sent
: Wird übermittelt, wenn eine Rechnung automatisch über die API oder über das Dashboard an eine/n Nutzer/in gesendet wird.invoice.deleted
: Wird übermittelt, wenn eine Rechnung mit Statusdraft
über die API oder das Dashboard gelöscht wird.invoice.paid
bzw.invoice.payment_failed
: Wird übermittelt, wenn ein Zahlungsversuch erfolgreich ist oder fehlschlägt.