Interroger des données Billing

Stripe Billing comprend différents composants qui, associés, fournissent des factures ponctuelles et périodiques. Les différents aspects des données de facturation sont disponibles dans plusieurs tables. Toutes les tables spécifiques à la facturation sont accessibles dans la section Facturation du schéma, les tables principales étant subscriptions et invoices.

Pour aller plus loin, vous pouvez utiliser les tables supplémentaires qui représentent les composants des abonnements et des factures, comme prices, products ou coupons. En outre, la table customers fait partie intégrante de la facturation et contient des données pour lesquelles vous devrez peut-être créer un rapport.

Abonnements

Chaque ligne du tableau subscriptions représente les données d’un objet Subscription individuel. Ces mêmes informations sont récupérées par l’API ou accessibles dans le Dashboard Stripe. Vous pouvez créer un rapport pour chaque abonnement créé sur votre compte.

Nous vous recommandons de commencer par cette table pour la création de rapports sur vos abonnés actuels. Vous pouvez la lier à d’autres tables et ainsi explorer vos données plus en détails.

L’exemple suivant récupère une liste d’abonnements marqués comme impayés, ainsi que les coordonnées du client, le cas échéant.

select
  subscriptions.id,
  subscriptions.customer_id,
  customers.email
from subscriptions
inner join customers
  on customers.id = subscriptions.customer_id
where
  subscriptions.status = 'unpaid'
limit 5

Clients

Les données relatives aux objets Customer figurent dans la table customers (elles ne font pas partie du groupe Tables Billing). Elles sont couramment utilisées dans le cadre des rapports basés sur la facturation et peuvent être liées à un certain nombre de tables. Elles sont également utiles si vous créez des paiements avec des informations de paiement enregistrées.

L’exemple suivant génère une liste de clients disposant d’un abonnement et qui bénéficient actuellement d’une période d’essai, avec leur ID et leur adresse e-mail.

select
  customers.id,
  customers.email,
  subscriptions.price_id
from subscriptions
inner join customers
on customers.id = subscriptions.customer_id
where subscriptions.status = 'trialing'
limit 5

Produits et tarifs

Les produits décrivent les articles que vos clients peuvent acheter avec un abonnement. Les tarifs sont liés aux produits et définissent le coût, l’intervalle de facturation et la devise. Lors de l’affichage des données dans le tableau subscriptions, subscriptions.price_id peut être lié à prices.id et prices.product_id peut être lié à products.id. L’exemple suivant renvoie une liste des abonnements actifs, ainsi que le nom du produit et son libellé de relevé bancaire.

select
  subscriptions.id,
  products.name,
  products.statement_descriptor
from subscriptions
inner join prices
  on subscriptions.price_id = prices.id
inner join products
  on prices.product_id = products.id
where
  subscriptions.status = 'active'
limit 10

Factures

La table invoices contient des données sur les objets Invoice. Chaque abonnement génère une facture récurrente qui représente le montant dû par le client, à savoir le montant de l’abonnement ainsi que tous les postes de facture supplémentaires qui ont été créés (et répertoriés comme tels).

Les factures sont constituées de postes de facture individuels. Ces postes correspondent aux abonnements pour lesquels le client est facturé, ainsi qu’aux postes de facture qui ont été créés et appliqués à la facture. Pour décomposer une facture et analyser chacun de ses postes, utilisez la table invoice_line_items.

La colonne source_id de cette table contient l’ID de l’abonnement (par exemple, sub_IjF5M25FJP81Ruw) ou du poste de facture (par exemple, ii_XjOEUeKdFTCCtQX) auquel correspond le poste. La colonne source_type permet de déterminer si les postes représentent un abonnement ou un poste de facture.

Contrairement à d’autres clés étrangères, la colonne subscription de la table invoice_line_items n’est pas toujours renseignée. Si le poste de facture correspondant est un abonnement, cette colonne est vide : son ID apparaît déjà dans la colonne source_id.

Postes de facture

Les données relatives aux postes de facture sont disponibles dans la table invoice_items. Les postes de facture sont couramment utilisés pour spécifier un montant supplémentaire (ou déduire un montant) qui est appliqué à la facture suivante au début du cycle de facturation suivant. Par exemple, vous pouvez créer un poste de facture si vous devez facturer votre client car il a dépassé son plafond mensuel, ou si vous devez offrir un crédit sur la facture suivante pour un service non utilisé.

L’exemple suivant récupère toutes les factures et tous les ID de paiement associés pour un abonnement spécifique.

select
  id,
  charge_id,
  amount_due
from invoices
where subscription_id = 'sub_ALJXL9gBYtv6GJ'

Totaux de factures et ristournes

Le sous-total de la facture correspond à la somme de tous les abonnements, postes de facture et calculs au prorata sur la facture avant l’application d’une ristourne. Le total de la facture correspond au montant après l’application des ristournes et des taxes :

invoice.total = invoice.subtotal - discount + invoice.tax

Aucune colonne ne correspond au montant de la ristourne sur une facture. Vous pouvez cependant le calculer à l’aide des du total, du sous-total et du montant de la taxe :

discount = invoice.total - invoice.tax - invoice.subtotal

Utilisation des dates et des périodes de facturation

Dans le cadre d’un abonnement, le client est facturé au début de chaque période de facturation. La date exacte est précisée dans la valeur period d’un poste de facture. Par exemple, un client disposant d’un abonnement mensuel est facturé au début de chaque mois. S’il annule son abonnement, ce dernier reste actif jusqu’à la fin du mois, date à laquelle l’abonnement prend fin.

Les valeurs period_start et period_end d’une facture correspondent à la date de création des postes de facture. Elles n’indiquent pas forcément la période de facturation du client. Par exemple, si un client est facturé le 1er de chaque mois et qu’il dépasse son plafond mensuel le 15, vous pouvez créer un poste de facture pour les frais supplémentaires facturés au client. Ce poste est ensuite inclus dans la facture suivante, qui est créée le 1er du mois suivant. Lorsque la facture suivante est générée, la date period_start correspond au 15 du mois précédent : date à laquelle le poste supplémentaire a été créé pour la première fois.

Bons de réduction et ristournes

Un objet Coupon correspond à un montant ou à un pourcentage de ristourne pouvant s’appliquer à des abonnements ou des clients. Une ristourne est l’application d’un bon de réduction, représenté par un objet Discount.

Les réductions ne sont pas compilées séparément. En revanche, vous pouvez lier coupon.id à customers.discount_coupon_id ou à subscriptions.discount_coupon_id. Cette action permet de renvoyer les informations du bon de réduction pour la réduction qui a été appliquée. Par exemple, la requête suivante renvoie une liste des abonnements pour lesquels un bon de réduction a été appliqué afin de créer une réduction, ainsi que le montant ou le pourcentage de la réduction.

select
  coupons.id,
  coupons.amount_off,
  coupons.percent_off
from coupons
where valid = false
limit 5