Rechnungsposten gruppieren

Rechnungsposten dynamisch filtern und gruppieren.

Sie können Ihren Kundinnen und Kunden dabei helfen, Ihre Rechnungen (einschließlich PDFs, gehostete Rechnungsseite und Rechnungs-E-Mails) besser zu verstehen, indem Sie die Rechnungsposten in Kategorien unterteilen und in verschiedenen Gruppen anzeigen. Sie können auch Gruppen von Einzelposten ausblenden. Dies ist hilfreich, wenn einige Einzelposten übermäßig detailliert sind: Sie können sie so konfigurieren, dass nur die Zwischensumme auf Gruppenebene für Ihre Kundinnen/Kunden sichtbar ist.

In diesem Leitfaden wird beschrieben, wie Sie einmalige Rechnungen und Abonnementrechnungen organisieren, indem Sie dynamische Filter und Gruppen im Stripe-Dashboard erstellen.

Gruppieren Sie Rechnungsposten dynamisch mit CEL-Ausdrücken.

Nicht gruppierte Posten

Gruppierte Posten mithilfe von Übersichtsposten (ausgeblendete Gruppe „Red items“)

Bevor Sie beginnen

Um die Gruppierung von Posten zu konfigurieren, müssen Sie die Funktion für Rechnungsvorlagen verwenden. Mit Rechnungsvorlagen definieren Sie Regeln und Vorlagen mithilfe von CEL-Ausdrücken (Common Expression Language). Weitere Informationen zu CEL finden Sie in der Sprachdefinition auf GitHub. Im Zusammenhang mit Rechnungsvorlagen stellen wir einige Beispiele zur Verfügung. Sie sollten jedoch zunächst die offizielle Definition der Sprache auf GitHub lesen und verstehen. Sie können auch mit einem gängigen Use case beginnen.

Einschränkungen

Diese Funktion weist einige Einschränkungen auf:

Sie können CEL-Ausdrücke nur auf Rechnungen anwenden, die über das Dashboard erstellt wurden.
Jeder CEL-Ausdruck hat eine maximale Länge von 1024 Zeichen.
Eine Vorlage verfügt über maximal 10 Gruppierungsrichtlinien für Posten.
Für jeden CEL-Ausdruck gilt eine Beschränkung der Erweiterungstiefe von 1. So wird beispielsweise line_item.invoice_item.expand().description unterstützt, aber nicht line_item.subscription.expand().default_payment_method.expand().type.
CEL-Ausdrücke unterstützen nicht jedes Feld im Rechnungspostenobjekt in der öffentlichen API.
Für CEL-Ausdrücke wird die API-Version 2022-11-15 als zugrunde liegende Ressource verwendet. Spätere API-Versionen und Vorschaufunktionen werden für die Dauer der Beta nicht automatisch unterstützt.

Rechnungsposten gruppieren

Vorlage zum Darstellen von Rechnungen erstellen

Gehen Sie im Stripe-Dashboard zu Einstellungen > Rechnungsvorlage.
Klicken Sie im Abschnitt Vorlagen auf + Vorlage erstellen.
Benennen Sie Ihre Vorlage. Sie verwenden den Vorlagennamen, wenn Sie die Vorlage auf ein Abonnement oder eine einmalige Rechnung anwenden.

Richtlinie zur Vorlage hinzufügen

Nachdem Sie die Vorlage erstellt haben, fügen Sie eine Postengruppierungsrichtlinie hinzu. Diese Richtlinien erstellen Sie in CEL. Dadurch erhält Stripe die Möglichkeit, Posten dynamisch zu filtern und zu gruppieren.

Best Practices

When you create a template, keep in mind:

Die Reihenfolge der Richtlinien ist wichtig. Wenn beispielsweise die erste Richtlinie alle Posten abruft, die die Filterbedingung erfüllen, greift die zweite Richtlinie nach der ersten Richtlinie alle verbleibenden Posten auf, die sich noch nicht in einer Gruppe befinden.
expand() ist ein Stripe-spezifisches Makro zum Erweitern von Feldern im API-Objekt. Weitere Informationen finden Sie im Abschnitt „Stripe-spezifische CEL-Ausdrucksmakros“.

Einen CEL-Ausdruck erstellen

Für CEL-Ausdrücke der Rechnungsvorlage wird ein Postenobjekt als Eingabe verwendet. Sie können alle Felder dieses Objekts in einem Ausdruck verwenden. Zum Beispiel:

line_item.field_name
line_item.description

Sie können ID-Felder, die auf andere Stripe-Objekte verweisen, wie ein Abonnement oder subscription_item, mit der Funktion expand() erweitern. So greifen Sie beispielsweise auf die Metadaten eines Abonnements zu:

line_item.subscription.expand().metadata

Häufiger Fehler

Sie können die Erweiterung nur eine Ebene nach unten durchführen. Beispielsweise können Sie die Felder für Zahlungsmethode und -typ eines Abonnements nicht erweitern. Dies wird derzeit nicht unterstützt: line_item.subscription.expand().default_payment_method.expand().type

Stripe-specific CEL expression macros

In addition to the list of standard CEL expression macros, we support the following Stripe-specific function:

expand() : Erweitert öffentlich erweiterbare API-Felder. In einem CEL-Ausdruck gibt beispielsweise line_item.invoice_item die Rechnungsposten-ID zurück. Mit line_item.invoice_item.expand() wird das vollständige Rechnungspostenobjekt zurückgegeben.

Line item grouping fields

Eine Postengruppierung hat drei Felder:

Feld Typ Beschreibung

Feld	Typ	Beschreibung
Group by	CEL-Ausdruck `<line_item => string>`	Steuert die Gruppierung von Posten. Wird für jeden Posten auf der Rechnung, der nicht herausgefiltert wurde, ausgewertet, und gibt eine Zeichenfolge zurück. Posten mit derselben Ergebniszeichenfolge werden unter einem Übersichtsposten zusammengefasst, wobei die Ergebniszeichenfolge zur Beschreibung des Übersichtspostens wird. Wenn Sie beispielsweise statische Postennamen wie „Bestellnummer“ gruppieren möchten, lautet der CEL-Ausdruck `PO Number`. Wenn Sie Posten mithilfe von „PO“ aus den Metadaten eines Postens dynamisch gruppieren möchten, lautet der CEL-Ausdruck: `'PO Number' + line_item.invoice_item.expand().metadata['PO']` Mit diesem Ausdruck wird ein Posten mit `metadata['PO'] = 123` in „Bestellnummer: 123“ ausgewertet. Wenn mehrere Posten in genau die gleiche Zeichenfolge ausgewertet werden, werden sie unter einem Übersichtsposten gruppiert, wobei die Beschreibung „Bestellnummer: 123“ lautet.
Filtern nach	CEL Expression `<line_item => boolean>`	Filtert Posten in einer Richtlinie. Dieser Ausdruck wird für jeden Rechnungsposten auf der Rechnung ausgewertet. Wenn ein bestimmter Rechnungsposten mit dem Filter übereinstimmt, wird er der für diese Richtlinie definierten Rechnungspostengruppe hinzugefügt. Wenn Sie beispielsweise Einzelposten mit einer Bestellnummer gruppieren möchten, verwenden Sie `has(line_item.invoice_item.expand().metadata.PO)`. Wenn die Rechnungspostenressource des Einzelpostens das Metadatenfeld `PO` aufweist, gibt der Ausdruck `true` zurück. Andernfalls wird `false` zurückgegeben.
Einzelposten ausblenden	Umschalten	Steuert, ob die Übersichtsposten, die aus einer Richtlinie zur Gruppierung von Rechnungsposten gebildet wurden, aus- oder eingeblendet werden sollen. Übersichtsposten werden standardmäßig eingeblendet.

Group by

CEL-Ausdruck <line_item => string>

Steuert die Gruppierung von Posten. Wird für jeden Posten auf der Rechnung, der nicht herausgefiltert wurde, ausgewertet, und gibt eine Zeichenfolge zurück. Posten mit derselben Ergebniszeichenfolge werden unter einem Übersichtsposten zusammengefasst, wobei die Ergebniszeichenfolge zur Beschreibung des Übersichtspostens wird.

Wenn Sie beispielsweise statische Postennamen wie „Bestellnummer“ gruppieren möchten, lautet der CEL-Ausdruck PO Number.

Wenn Sie Posten mithilfe von „PO“ aus den Metadaten eines Postens dynamisch gruppieren möchten, lautet der CEL-Ausdruck:

'PO Number' + line_item.invoice_item.expand().metadata['PO']

Mit diesem Ausdruck wird ein Posten mit metadata['PO'] = 123 in „Bestellnummer: 123“ ausgewertet. Wenn mehrere Posten in genau die gleiche Zeichenfolge ausgewertet werden, werden sie unter einem Übersichtsposten gruppiert, wobei die Beschreibung „Bestellnummer: 123“ lautet.

Filtern nach

CEL Expression <line_item => boolean>

Filtert Posten in einer Richtlinie. Dieser Ausdruck wird für jeden Rechnungsposten auf der Rechnung ausgewertet. Wenn ein bestimmter Rechnungsposten mit dem Filter übereinstimmt, wird er der für diese Richtlinie definierten Rechnungspostengruppe hinzugefügt.

Wenn Sie beispielsweise Einzelposten mit einer Bestellnummer gruppieren möchten, verwenden Sie has(line_item.invoice_item.expand().metadata.PO). Wenn die Rechnungspostenressource des Einzelpostens das Metadatenfeld PO aufweist, gibt der Ausdruck true zurück. Andernfalls wird false zurückgegeben.

Einzelposten ausblenden Umschalten Steuert, ob die Übersichtsposten, die aus einer Richtlinie zur Gruppierung von Rechnungsposten gebildet wurden, aus- oder eingeblendet werden sollen. Übersichtsposten werden standardmäßig eingeblendet.

Vorlagen zum Darstellen von Rechnungen auf eine einmalige Rechnung oder ein Abonnement anwenden

Um die Richtlinie zur Gruppierung von Rechnungsposten zu verwenden, wenden Sie die Vorlage auf eine Rechnung oder ein Abonnement an.

Verwenden Sie den Rechnungs-Editor im Stripe-Dashboard, um Vorlagen zum Darstellen von Rechnungen auf neue Rechnungen und Rechnungsentwürfe anzuwenden.

Verwenden Sie den Abonnement-Editor im Stripe-Dashboard, um die Vorlage zum Darstellen von Rechnungen auf ein Abonnement anzuwenden. Bei allen zukünftigen Rechnungen, die aus diesem Abonnement generiert werden, werden die Gruppierungsrichtlinien für Rechnungsposten dieser Rendering-Vorlage verwendet. Sie können den Vorlagenentwurf auf Abonnementrechnungen anwenden. Sie können die Vorlage nicht auf finalisierte Rechnungen anwenden.

Hier erfahren Sie mehr über Rechnungsübergänge und die Finalisierung.

Anwendungsfälle

In der folgenden Tabelle finden Sie einige gängige Beispiele für Gruppierungsrichtlinien.

Use case	Details und Beispiel
Metadaten nach Rechnungsposten gruppieren	Möglicherweise haben Sie einen vertriebsorientierten Prozess, der verschiedene Bestellnummern mit jedem Ihrer Rechnungsposten mit Metadaten namens „PO“ verknüpft. In diesem Beispiel werden mithilfe des Felds Gruppieren nach Gruppen für jede Bestellnummer erstellt und die Einzelposten aufgelistet, die dieser Bestellnummer in ihrem Metadatenfeld entsprechen. Gruppieren nach: `'PO - ' + line_item.invoice_item.expand().metadata.purchase_order_number` Filtern nach: `has(line_item.invoice_item.expand().metadata.purchase_order_number)`
Nach Preis-Metadaten gruppieren	Möglicherweise möchten Sie Rechnungsposten nach den Preis-Metadaten gruppieren, um die Rechnung nach der Art des Preises zu gliedern, zu dem gekauft wurde. Die Rechnung wird entsprechend der von Ihnen in den Preis-Metadaten angegebenen Zeichenfolge `section` unterteilt. Gruppieren nach: `line_item.price.metadata.section` Filtern nach: `has(line_item.price.metadata.section)`
Nach Anteilen gruppieren	Möglicherweise haben Sie viele anteilige Einzelposten in Ihrer Abonnementrechnung und möchten Ihre Rechnung für Kundinnen und Kunden vereinfachen. In diesem Beispiel werden Einzelposten mit einem anteiligen Betrag von mehr als 0 USD in der Gruppe „Gutschriften“ und negative Einzelposten in der Gruppe „Lastschriften“ zusammengefasst. Gruppieren nach: `'Proration ' + (line_item.amount > 0 ? 'Debits' : 'Credits')` Filtern nach: `line_item.proration`
Posten nach Beschreibung gruppieren	Alle nicht gruppierten Posten werden standardmäßig unter dem Abschnitt Sonstiges einer Übersicht gruppiert. Wenn Sie ansonsten nicht gruppierte Posten nach ihrer Beschreibung auflisten möchten, können Sie den Abschnitt Sonstiges unter einer Übersicht erweitern. Um zu verhindern, dass andere Gruppierungsrichtlinien außer Kraft gesetzt werden, stellen Sie sicher, dass dies das letzte Element in der Richtlinienliste ist. Gruppieren nach: `line_item.description`