Grouper des sous-postes de facture

Filtrez et groupez les sous-postes de facture de manière dynamique.

Pour aider vos clients à mieux comprendre vos factures (tant sous forme de PDF que via la page de facture hébergée ou par e-mail), vous pouvez catégoriser les postes de facture et les regrouper par catégorie. Vous pouvez également masquer des groupes de postes de facture, ce qui peut être utile si certains postes sont trop détaillés : vous pouvez alors faire en sorte que seul le sous-total de certains groupes soit visible de vos clients.

Ce guide décrit comment organiser les factures ponctuelles et les factures d’abonnement en créant des groupes et des filtres dynamiques dans le Dashboard Stripe.

Regroupez les sous-postes de facture de manière dynamique à l’aide d’expressions CEL.

Facture au format PDF sans poste récapitulatif

Postes de facture non groupés

Facture au format PDF avec postes récapitulatifs

Postes de factures groupés avec des postes récapitulatifs (groupe « Red items » réduit)

Avant de commencer

Pour configurer le regroupement des postes de facture, vous devez utiliser la fonctionnalité Modèles de facture. Celle-ci vous permet de définir des règles et des modèles à l’aide d’expressions du langage d’expression commun (CEL). Pour en savoir plus sur le CEL, consultez la définition sur GitHub. Nous fournissons quelques exemples dans le contexte des modèles de factures, mais nous vous recommandons de lire et de comprendre d’abord la définition du langage. Vous pouvez également commencer par un cas d’usage courant.

Restrictions

Cette fonctionnalité présente certaines limites :

Vous pouvez uniquement appliquer des expressions CEL aux factures créées à partir du Dashboard.
Chaque expression CEL a une longueur maximale de 1 024 caractères.
Un modèle dispose d’un maximum de 10 politiques de regroupement des postes de facture.
Chaque expression CEL a une limite de développement de 1. Par exemple, nous prenons en charge line_item.invoice_item.expand().description mais pas line_item.subscription.expand().default_payment_method.expand().type.
Les expressions CEL ne sont pas compatibles avec tous les champs de l’objet Invoice Item dans l’API publique.
Les expressions CEL utilisent la version de l’API 2022-11-15 comme ressource sous-jacente. Les versions ultérieures de l’API et les fonctionnalités de prévisualisation ne sont pas automatiquement prises en charge pendant la phase bêta.

Grouper des sous-postes de facture

Créer un modèle de rendu de facture

Accédez à Paramètres > Modèle de facture dans le Dashboard Stripe.
Dans la section Modèles, cliquez sur + Créer un modèle.
Nommez votre modèle. Ce nom vous servira au moment d’appliquer le modèle à une facture ponctuelle ou une facture d’abonnement.

Ajouter une politique au modèle

Une fois votre modèle créé, ajoutez-y une stratégie de regroupement des postes de facture, rédigée en CEL, ce qui permet à Stripe de filtrer et de regrouper les postes de facture de manière dynamique.

Bonnes pratiques

Lors de la création d’un modèle, gardez à l’esprit les points suivants :

L’ordre des politiques est important. Par exemple, si la première politique sélectionne tous les postes qui répondent à la condition filter, la deuxième politique sélectionne tous les postes restants qui ne sont pas encore dans un groupe après l’application de la première politique.
expand() est une macro spécifique à Stripe pour développer les champs de l’objet API. Consultez la section dédiée aux macros d’expression CEL propres à Stripe.

Rédiger une expression CEL

Les expressions CEL des modèles de facture prennent pour entrée un objet poste de facture. Vous pouvez utiliser n’importe quel champ de cet objet dans une expression. Par exemple :

line_item.field_name
line_item.description

Vous pouvez développer des champs d’ID qui pointent vers d’autres objets Stripe, comme un objet subscription ou subscription_item, grâce à la fonction expand(). Par exemple, pour accéder aux métadonnées d’un abonnement :

line_item.subscription.expand().metadata

Erreur fréquente

Vous ne pouvez développer qu’un seul niveau. Vous ne pouvez donc pas développer les champs Type et Moyen de paiement d’un abonnement. Par exemple, cette expression n’est pas pris en charge à l’heure actuelle : line_item.subscription.expand().default_payment_method.expand().type

Macros d’expressions CEL propres à Stripe

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

expand() : développe les champs d’API publiquement développables par l’utilisateur. Par exemple, dans une expression CEL, line_item.invoice_item renvoie l’ID du poste de facture, tandis que line_item.invoice_item.expand() renvoie l’objet poste de facture complet.

Champs de regroupement des postes

Un regroupement de postes comporte trois champs :

Champ Type Description

Champ	Type	Description
Grouper par	Expression CEL `<line_item => string>`	Contrôle le regroupement de postes. Elle est appliquée à chaque poste de la facture qui n’a pas été filtré et renvoie une chaîne. Les postes générant la même chaîne sont regroupés sous un poste récapitulatif, et la chaîne renvoyée est utilisée comme description du poste récapitulatif. Par exemple, si vous souhaitez regrouper des noms de postes de facture statiques, tels que « PO Number » (numéro de commande), l’expression CEL sera `PO Number`. Si vous souhaitez regrouper de manière dynamique les postes de facture pour lesquelles « PO » figure dans les métadonnées, l’expression CEL correpondante serait : `'PO Number' + line_item.invoice_item.expand().metadata['PO']` Avec cette expression, un poste de facture doté de l’attribut `metadata['PO'] = 123` sera interprété comme « PO Number : 123 ». Si plusieurs postes génèrent exactement la même chaîne, ils sont regroupés sous un poste récapitulatif dont la description est « PO Number : 123 ».
Filtrer par	Expression CEL `<line_item => boolean>`	Filtre les éléments de ligne d’une politique. Cette expression est évaluée pour chaque sous-poste de facture. Tous ceux qui correspondent au filtre sont ajoutés au groupe de sous-postes de facture défini pour cette politique. Par exemple, si vous souhaitez regrouper les postes qui ont un numéro de bon de commande, utilisez l’expression `has(line_item.invoice_item.expand().metadata.PO)`. Si le poste de facture utilisé comme ressource a un champ de métadonnées `PO`, l’expression renvoie la valeur `true`. Dans le cas contraire, elle renvoie la valeur `false`.
Masquer les postes	Afficher/masquer	Contrôle s’il faut réduire ou développer les postes récapitulatifs formés à partir d’une politique de regroupement des sous-postes de facture. Les postes récapitulatifs sont développés par défaut.

Grouper par

Expression CEL <line_item => string>

Contrôle le regroupement de postes. Elle est appliquée à chaque poste de la facture qui n’a pas été filtré et renvoie une chaîne. Les postes générant la même chaîne sont regroupés sous un poste récapitulatif, et la chaîne renvoyée est utilisée comme description du poste récapitulatif.

Par exemple, si vous souhaitez regrouper des noms de postes de facture statiques, tels que « PO Number » (numéro de commande), l’expression CEL sera PO Number.

Si vous souhaitez regrouper de manière dynamique les postes de facture pour lesquelles « PO » figure dans les métadonnées, l’expression CEL correpondante serait :

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

Avec cette expression, un poste de facture doté de l’attribut metadata['PO'] = 123 sera interprété comme « PO Number : 123 ». Si plusieurs postes génèrent exactement la même chaîne, ils sont regroupés sous un poste récapitulatif dont la description est « PO Number : 123 ».

Filtrer par

Expression CEL <line_item => boolean>

Filtre les éléments de ligne d’une politique. Cette expression est évaluée pour chaque sous-poste de facture. Tous ceux qui correspondent au filtre sont ajoutés au groupe de sous-postes de facture défini pour cette politique.

Par exemple, si vous souhaitez regrouper les postes qui ont un numéro de bon de commande, utilisez l’expression has(line_item.invoice_item.expand().metadata.PO). Si le poste de facture utilisé comme ressource a un champ de métadonnées PO, l’expression renvoie la valeur true. Dans le cas contraire, elle renvoie la valeur false.

Masquer les postes Afficher/masquer Contrôle s’il faut réduire ou développer les postes récapitulatifs formés à partir d’une politique de regroupement des sous-postes de facture. Les postes récapitulatifs sont développés par défaut.

Appliquer le modèle de rendu de facture à une facture ponctuelle ou à un abonnement

Pour utiliser la politique de regroupement des sous-postes de facture, appliquez le modèle à une facture ou à un abonnement.

Utilisez l’éditeur de factures dans le Dashboard Stripe pour appliquer des modèles de rendu de facture aux nouvelles factures et aux brouillons de factures.

Utilisez l’éditeur d’abonnement du Dashboard Stripe pour appliquer le modèle de rendu de facture à un abonnement. Toutes les factures futures générées à partir de cet abonnement utiliseront les stratégies de regroupement des sous-postes de facture de ce modèle de rendu. Vous pouvez appliquer le modèle aux factures d’abonnement, mais vous ne pouvez pas l’appliquer aux factures finalisées.

En savoir plus sur les changements d’état et sur la finalisation des factures.

Cas d’usage

Le tableau suivant fournit quelques exemples de politiques de regroupement courantes.

Cas d’usage	Détails et exemple
Grouper par métadonnées de sous-poste de facture	Certaines entreprise utilisent un processus commercial qui relie différents numéros de bon de commande à chaque sous-postes de facture à l’aide d’une métadonnée nommée « PO ». Dans cet exemple, le champ Grouper par crée des groupes pour chaque numéro de bon de commande et répertorie les postes de facture correspondant à ce numéro à partir de leur champ de métadonnées. Grouper par : `'PO - ' + line_item.invoice_item.expand().metadata.purchase_order_number` Filtrer par : `has(line_item.invoice_item.expand().metadata.purchase_order_number)`
Grouper par métadonnées de tarif	Vous pouvez également choisir de regrouper les sous-postes de facture par métadonnées de tarif afin d’organiser la facture par type de tarif. La facture est divisée en plusieurs parties selon la chaîne `section` que vous spécifiez dans les métadonnées de tarif. Grouper par : `line_item.price.metadata.section` Filtrer par : `has(line_item.price.metadata.section)`
Grouper par prorata	Si vos factures d’abonnement incluent de nombreux postes de facture correspondant à des calculs au prorata, vous voudrez peut-être simplifier votre facture pour les clients. Cet exemple regroupe les postes dont le montant calculé au prorata est supérieur à 0 USD dans un groupe appelé « Crédits » et les postes négatifs dans un groupe appelé « Débits ». Grouper par : `'Proration ' + (line_item.amount > 0 ? 'Debits' : 'Credits')` Filtrer par : `line_item.proration`
Grouper les postes de facture par description	Tous les postes de facture non regroupés figurent par défaut dans la section Autre d’un récapitulatif. Si vous souhaitez répertorier les postes non regroupés par description, vous pouvez développer la section Autre sous un récapitulatif. Pour éviter de remplacer une autre stratégie de regroupement, il doit s’agir du dernier élément de la liste des stratégies. Grouper par : `line_item.description`