Facturer avec Stripe

Utilisez l’intégration native Stripe de Metronome pour facturer vos clients via Stripe. Avec l’intégration Stripe, lorsqu’une facture est finalisée à la fin de la période de facturation, Metronome crée automatiquement une facture correspondante dans Stripe pour collecter le paiement. S’appuyer sur les capacités avancées de facturation de Stripe vous aide à réduire le churn involontaire en maximisant votre taux de succès de paiement pour des scénarios comme les clients en paiement à l’usage. Ce guide décrit comment configurer Stripe comme votre fournisseur de facturation externe, interagir avec l’intégration et comprendre comment Metronome gère les limites de Stripe.

Configurer l’intégration Stripe

La configuration de l’intégration Stripe implique de connecter Metronome et Stripe puis de configurer les paramètres de facturation.

Connecter Metronome et Stripe

Lorsque vous connectez votre compte Stripe à Metronome, Metronome peut créer automatiquement des factures dans Stripe. La connexion implique d’accorder à Metronome les permissions d’écrire et de lire des données en votre nom sur votre compte Stripe. Les clients connectent souvent Stripe aux environnements de production et sandbox de Metronome. Cela leur permet de tester de bout en bout d’éventuels changements de prix ou autres mises à jour de facture avant de les activer pour les clients de production. Lorsque vous configurez l’intégration Stripe dans Metronome Sandbox, Metronome se connecte automatiquement à votre mode test Stripe afin que vous puissiez tester votre intégration de bout en bout avec la création de factures et l’encaissement de paiements. Pour connecter Metronome et Stripe :

Authentifiez votre compte Stripe depuis Metronome. Rendez-vous dans General Settings - Integrations → cliquez sur Enable et complétez l’assistant Stripe.
Configurez une connexion Stripe depuis chaque environnement Metronome via lequel vous souhaitez envoyer des factures, comme les environnements de production et sandbox.
Activez les capacités de relance automatique de paiement de Stripe pour améliorer le succès du paiement des factures.

Connecter Metronome à plusieurs comptes Stripe

Metronome prend en charge la facturation multi-entités avec Stripe pour vous permettre de connecter votre environnement Metronome à plusieurs comptes Stripe. Cette fonctionnalité permet aux entreprises complexes de gérer leur facturation et leurs finances en tant qu’unités d’affaires distinctes. Pour configurer plusieurs comptes Stripe :

Allez dans Connections - > Integrations
Sélectionnez Stripe - > Add another
Sélectionnez le compte Stripe approprié

Une fois terminé, vous verrez une ligne dans Active Integrations pour chaque compte Stripe auquel Metronome est connecté. Vous pouvez créer un alias pour chaque compte afin de les identifier. Par exemple : Stripe NA et Stripe EU. Cet alias apparaîtra partout où le compte Stripe est référencé dans l’application Metronome.

AVERTISSEMENTSi vous utilisez la facturation multi-entités, vous devez utiliser delivery_method_id lors de la configuration de la billing configuration du client. Assurez-vous que votre flow d’inscription client utilise ce champ avant de configurer la facturation multi-entités. Voir définir la customer billing configuration pour plus de détails.

Configurer les paramètres globaux d’intégration optionnels

Après avoir connecté Metronome à Stripe, vous disposez d’options que vous pouvez configurer depuis la page General Settings - Integrations. Si vous êtes connecté à plusieurs comptes Stripe, vous devrez configurer les paramètres indépendamment pour chaque compte.

Paramètres de facture
Définir la date d’échéance de la facture	Stripe utilise par défaut des dates d’échéance de facture dans les 30 jours après leur envoi. Vous pouvez modifier cette option à une valeur différente. Ce paramètre n’a aucun effet pour les clients configurés pour être prélevés automatiquement.
Laisser les factures en brouillon	Par défaut, Metronome envoie toutes les factures à Stripe avec l’option `auto_advance` définie à true, permettant aux factures d’être finalisées dans Stripe immédiatement sans aucune action requise de votre part. Si vous préférez laisser les factures en brouillon pour pouvoir les revoir et les finaliser manuellement dans Stripe, cochez l’option « leave invoices as drafts » dans Metronome. Metronome définit alors `auto_advance` de Stripe à false.
Ignorer les factures à total zéro	Si la facturation Stripe est activée pour un client, toutes les factures finalisées dans Metronome sont envoyées à Stripe par défaut. L’option « skip zero-total invoices » limite cela à l’envoi des factures non nulles uniquement. Stripe impose des limites sur les montants minimaux de prélèvement. Par exemple, avec la devise USD, le prélèvement minimum autorisé est de $0,50. Si vous sélectionnez « skip zero-total invoices », Metronome ignore l’envoi à Stripe des factures inférieures au montant minimum de prélèvement pour la devise.
Aligner effective_at sur le dernier jour de la période	Par défaut, Stripe renseigne le champ « Invoice Date » sur les factures PDF et `effective_at` dans l’API avec la date à laquelle la facture est finalisée. Utilisez ce paramètre pour renseigner le champ `effective_at` avec la dernière date de la période de service de la facture (par exemple, le 31 octobre pour une facture du 1er au 31 octobre). Cela permet de s’assurer que les factures d’usage sont suivies par rapport à la bonne période comptable, en cohérence avec les pratiques de reconnaissance des revenus dans les systèmes financiers en aval. Ce paramètre n’est pas pris en charge avec Stripe Tax en raison d’une limitation de Stripe qui provoque l’échec de la synchronisation des factures.

Présentation de la facture
Afficher les lignes avec quantité zéro sur les factures Stripe	Si sélectionné, Metronome crée une ligne Stripe sur les factures Stripe pour toutes les charges, y compris celles ayant une quantité de zéro.
Toujours afficher les informations de prix et de quantité dans les descriptions de ligne des factures Stripe	Comme Stripe ne prend pas en charge les quantités décimales, Metronome affiche par défaut les quantités dans les descriptions de ligne si au moins une quantité sur une facture n’est pas un entier. En sélectionnant « always display quantities in line items », les quantités apparaîtront toujours dans les noms de ligne, que la facture comporte ou non des quantités non entières.

INFOCes paramètres sont appliqués par compte Stripe au niveau de l’environnement. Vous ne pouvez pas configurer de préférences spécifiques au client.

Créer des règles de mapping d’entité optionnelles

Par défaut, Metronome définit des métadonnées sur les objets de facture Stripe qu’il crée. Un des éléments qu’il définit est metronome_id, qui est l’ID de facture Metronome qui vous permet de mapper une facture Stripe à sa facture Metronome correspondante. Vous pouvez vouloir ajouter des métadonnées supplémentaires aux entités Stripe. Par exemple :

Ajouter des attributs comme le nom du contrat ou l’ID du contrat à la facture Stripe (visible par les clients) en mappant des champs personnalisés Metronome de contrat ou de grille tarifaire à des champs personnalisés de facture Stripe.
Ajouter des métadonnées comme la ligne de facture et les objets price de ligne de facture à la facture Stripe pour vos audits internes ou pour des intégrations en aval comme le calcul de taxes.

Pour configurer Metronome afin qu’il ajoute automatiquement vos propres métadonnées supplémentaires aux entités Stripe, modifiez les règles de mapping de l’intégration Stripe entre les champs personnalisés Metronome et les entités Stripe sur la page General Settings - Integrations. Si vous êtes connecté à plusieurs comptes Stripe, vous devrez configurer chacun de ces mappings individuellement. Exemple : assigner des lignes à des produits Stripe Un cas d’usage courant pour ajouter des métadonnées aux entités Stripe est d’assigner les lignes d’une facture Metronome à un produit existant dans Stripe. Pour ce faire :

Créez une clé de champ personnalisé sur l’entité produit Metronome : stripe_product_id.
Définissez la valeur de la clé de champ personnalisé que vous venez de créer pour chacun de vos produits dans Metronome.
Allez sur la page General Settings - Integrations et modifiez les règles de mapping pour mapper la clé de champ personnalisé Metronome stripe_product_id à invoiceitem.price de Stripe.

Obligatoire pour les engagements à paiement préalableSi vous utilisez des engagements à paiement préalable, chaque produit Metronome utilisé sur un engagement à paiement préalable doit avoir un champ personnalisé stripe_product_id mappé à un Stripe Product ID valide. Sans ce mapping, Stripe ne peut pas générer la ligne de facture et la tentative de paiement échouera, annulant l’engagement.

Définir la customer billing configuration

Pour déterminer quelles factures envoyer à Stripe, Metronome examine la billing_configuration de chaque client. La billing_configuration est un objet à l’intérieur de l’objet client Metronome qui capture des métadonnées supplémentaires nécessaires à la prise en charge des intégrations natives de Metronome. Cela inclut des informations comme le customer.id du fournisseur de facturation et les préférences de facture. Si la billing_configuration du client est définie sur Stripe, une facture Stripe est émise au client Stripe correspondant. Définissez la billing configuration pour un client dans l’application Metronome ou via l’API.

INFOSi vous êtes connecté à plusieurs comptes Stripe, vous ne pouvez définir la billing configuration que via l’API.

Pour l’API, définissez cette configuration pendant le processus de création du client à l’aide de l’endpoint /customers ou après que le client existe déjà avec /setCustomerBillingProviderConfigurations définissant la billing configuration. Pour définir une billing configuration, Metronome exige que vous spécifiiez soit un delivery_method, soit un delivery_method_id. Si vous vous connectez à un seul compte Stripe, utilisez delivery_method. Si vous vous connectez à plusieurs comptes Stripe, vous devez utiliser delivery_method_id. Metronome utilise cet ID pour déterminer vers quel compte Stripe chaque facture doit être envoyée.

INFOVous pouvez trouver le delivery_method_id en utilisant l’endpoint /listConfiguredBillingProviders pour récupérer les comptes Stripe configurés dans l’environnement Metronome.

Cet exemple de payload utilise l’endpoint /customers pour définir la billing configuration en utilisant delivery_method :

curl https://api.metronome.com/v1/customers \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_aliases": [
      "team@example.com"
    ],
    "name": "Example, Inc.",
    "customer_billing_provider_configurations": [{
      "billing_provider": "stripe",
      "configuration": {
        "stripe_customer_id": "cus_456",
        "stripe_collection_method": "charge_automatically"
      },
      "delivery_method": "direct_to_billing_provider"
    }]
  }'

Cet exemple de payload suivant utilise /setCustomerBillingProviderConfigurations pour définir la billing configuration d’un client existant en utilisant delivery_method_id :

curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491",
        "billing_provider": "stripe",
        "configuration": {
          "stripe_customer_id": "cus_1234",
          "stripe_collection_method": "charge_automatically"
        },
        "delivery_method_id": "5b95d955-b705-41c8-9d2e-34ccbdee5193"
      }
    ]
  }'

La billing configuration se compose de deux champs qui dictent comment la facture Stripe est créée :

stripe_customer_id : l’ID du client Stripe pour lequel une facture Stripe est émise.
stripe_collection_method : détermine comment encaisser le paiement pour le client. Stripe prend en charge deux méthodes d’encaissement :
- charge_automatically : Stripe tente de prélever la facture en utilisant le moyen de paiement par défaut attaché au client.
  charge_automatically nécessite qu’un moyen de paiement par défaut soit défini sur le client Stripe avant que la facture ne soit finalisée. Si aucun moyen de paiement par défaut n’est configuré, Stripe ne peut pas prélever la facture et le paiement échouera. Confirmez que le client a un moyen de paiement par défaut dans Stripe avant d’utiliser cette méthode d’encaissement.
- send_invoice : Stripe envoie par e-mail cette facture au client avec les instructions de paiement. Pour l’option send_invoice, vous devez spécifier de combien de jours dispose un client jusqu’à l’échéance du paiement. Cela correspond au champ days_until_due dans l’API Stripe. Par défaut, les factures Stripe sont dues 30 jours après leur création. L’API Metronome ne vous permet pas de définir cette valeur directement, mais vous pouvez mettre à jour ce paramètre sur la page General Settings - Integrations.

Définir la billing configuration du contrat

Metronome prend en charge la configuration de la facturation au niveau du contrat. Cela vous permet d’optimiser la facturation pour chaque contrat : vous pouvez envoyer les contrats de paiement à l’usage via Stripe, mais les contrats de niveau entreprise via AWS. Cet exemple de payload utilise l’endpoint /contracts/create pour définir la billing configuration :

curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "6ae46ff3-a73e-4553-a139-346eafcea608",
    "rate_card_id": "cfe45e46-0277-42e0-b66a-45ccbd028913",
    "starting_at": "2025-01-01T00:00:00.000Z",
    "billing_provider_configuration": {
      "billing_provider": "stripe",
      "delivery_method": "direct_to_billing_provider"
    }
  }'

Si vous êtes connecté à plusieurs comptes Stripe, un même client peut être mappé à plusieurs comptes Stripe. Lors de la création du contrat, utilisez billing_configuration_id qui peut être récupéré depuis l’endpoint /getCustomerBillingProviderConfigurations :

curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "6ae46ff3-a73e-4553-a139-346eafcea608",
    "rate_card_id": "cfe45e46-0277-42e0-b66a-45ccbd028913",
    "starting_at": "2025-01-01T00:00:00.000Z",
    "billing_provider_configuration": {
      "billing_provider_configuration_id": "561ea579-e830-41d9-9161-d35313c061c5"
    }
  }'

Ajouter un fournisseur de facturation à un contrat existant

Lorsque vous ajoutez une configuration de fournisseur de facturation à un contrat existant, Metronome n’envoie pas rétroactivement les factures précédemment finalisées à Stripe. Seules les factures qui se finalisent après l’ajout de la configuration au contrat sont envoyées à Stripe. La première facture envoyée à Stripe est la facture d’usage à terme échu de la période de facturation pendant laquelle la configuration a été ajoutée. Par exemple :

Date	Événement
1er janv.	Le contrat commence
1er févr.	La configuration du fournisseur de facturation est créée
15 avr.	La configuration est ajoutée au contrat
1er mai	Première facture envoyée à Stripe (usage à terme échu d’avril)

Metronome détermine la première facture à envoyer en fonction du moment où la configuration a été ajoutée au contrat, et non du moment où le contrat a commencé ou où la configuration a été créée.

Interagir avec l’intégration Stripe

Après avoir connecté Stripe à Metronome, utilisez l’API et l’application Metronome pour interagir avec votre intégration.

Suivre les statuts de facture Stripe dans Metronome

Metronome capture les événements webhook Stripe lorsque le statut d’une facture change. Les statuts de facture Stripe sont accessibles dans Metronome dans le cadre de la réponse lors de la récupération des factures depuis l’endpoint API list invoices.

{
  "id": "INVOICE_ID",
  ...
  "external_invoice": {
    "billing_provider_type": "stripe",
    "invoice_id": "in_123",
    "issued_at_timestamp": "2024-09-30T16:40:40.30184+00:00",
    "external_status": "PAID"
  },
  ...
}

Ces statuts sont accessibles dans votre entrepôt de données via data export de Metronome. Ils incluent :

Événement webhook Stripe	external_status dans Metronome
invoice.finalized	FINALIZED
invoice.marked_uncollectible	UNCOLLECTIBLE
invoice.paid	PAID
invoice.payment_failed	PAYMENT_FAILED
invoice.payment_succeeded	PAID
invoice.voided	VOID
invoice.deleted	DELETED

INFOSi la configuration globale est définie sur Leave invoices as drafts, Stripe ne retourne pas de statut et vous ne verrez pas de statut de facture Stripe dans Metronome.

Calculer dynamiquement la taxe de vente

L’intégration native Stripe de Metronome prend en charge les fournisseurs de taxe Anrok, Avalara et Stripe Tax pour ajouter la taxe à une facture créée dans Stripe. Le choix dépend de votre fournisseur de facturation et de vos besoins de conformité :

Fournisseur	Intégration de facturation
Stripe Tax	Oui
Anrok	Oui (via l’application Stripe)
Avalara	Oui (via l’application Stripe)

Quel que soit le fournisseur choisi, le flow général en utilisant la facturation Stripe est :

Le relevé d’usage Metronome se finalise, créant une facture en brouillon correspondante dans Stripe.
Metronome transmet les données de mapping d’entité (IDs de produit, métadonnées) à la facture Stripe.
Votre fournisseur de taxe calcule la taxe sur la facture Stripe.
La facture est finalisée dans Stripe avec la taxe incluse.

Pour les instructions de configuration, consultez le guide dédié à votre fournisseur : Stripe Tax, Anrok ou Avalara. Lors de l’intégration avec Avalara ou Anrok directement via Stripe (et non via une application Stripe), Metronome accorde par défaut jusqu’à une heure pour que la taxe soit appliquée aux factures en brouillon avant la finalisation. Notez qu’après une heure, la facture est finalisée dans Stripe. Si vous préférez garder ces factures en brouillon indéfiniment, activez l’option « Leave invoices as drafts » dans vos paramètres d’intégration Stripe. Si vous utilisez un fournisseur de taxe non listé ci-dessus, ou si vous n’utilisez pas Stripe pour la facturation, contactez votre représentant Metronome pour des conseils sur la configuration de la taxe.

Timing du paiement pour les factures `charge_automatically`

Metronome finalise les factures immédiatement à la fin de la période de facturation — il n’y a pas d’attente avant que la facture soit envoyée à Stripe. Cependant, lorsque Metronome envoie une facture finalisée à Stripe avec charge_automatically, Stripe attend jusqu’à une heure après la livraison du webhook invoice.created avant de tenter le paiement. La facture reste à l’état open pendant cette fenêtre. Ce délai est un comportement côté Stripe qui s’applique spécifiquement aux factures finalisées manuellement via l’API (ce qui est la façon dont Metronome soumet toutes les factures aujourd’hui). Il n’est pas configurable dans le Dashboard Stripe — le paramètre « grace period » dans Stripe contrôle uniquement la transition draft → finalized, et non la transition finalized → tentative de paiement. Ce délai ne s’applique pas à :

Les factures de recharge automatique.
Les engagements à paiement préalable, où le paiement est collecté manuellement.

Si vous constatez des délais supérieurs à une heure : Stripe se rabat sur une attente de 72 heures lorsque la livraison du webhook invoice.created échoue. Si des factures restent à l’état open bien au-delà d’une heure, vérifiez que votre endpoint webhook Stripe est correctement configuré et renvoie une réponse 2xx. Contournement pour éviter l’attente d’une heure : confirmez vous-même le payment intent immédiatement après que la facture est finalisée :

Écoutez le webhook Stripe invoice.finalized ou payment_intent.created.
Extrayez l’ID du payment_intent du payload de l’événement.
Appelez POST /v1/payment_intents/:id/confirm sur l’API Stripe.

Cela réduit le temps entre la finalisation et la tentative de paiement à quelques secondes.

Écouter les erreurs

Des erreurs de facturation peuvent survenir. Par exemple, des erreurs se produisent lorsque les clients Stripe n’existent pas. Pour recevoir des notifications de Metronome lorsqu’une erreur d’envoi d’une facture à Stripe survient, écoutez le type de webhook invoice.billing_provider_error. Lors de la réception de ces webhooks, déclenchez des notifications et actions internes pour garantir la bonne facturation de vos clients.

Comment Metronome gère les limitations de Stripe

Stripe impose certaines limites sur les factures qui peuvent provoquer des écarts ou des problèmes lors de la facturation des clients. Ce tableau décrit comment Metronome gère ces limitations.

Limitation Stripe	Approche de Metronome
Stripe ne prend pas en charge les quantités décimales	Si la quantité est une décimale pour au moins une ligne de la facture, Metronome définit la quantité à 1 pour toutes les lignes Stripe de la facture. Metronome fournit la vraie quantité dans le cadre de la description de chaque ligne.
Stripe impose un maximum de 250 lignes sur ses factures	Si une facture client dans Metronome dépasse 250 lignes, la facture est condensée en une seule ligne, étiquetée avec le nom de votre société et le total de la facture comme prix associé. Offrez à vos clients une visibilité complète sur la facture (avec toutes les lignes) grâce à des tableaux de bord qui exposent les factures dans votre interface.
Stripe n’autorise pas de prélèvement supérieur à 999 999,99 USD	Metronome génère une erreur lors de la création d’une facture avec un montant supérieur au maximum Stripe. Contactez votre représentant Stripe et votre représentant Metronome pour augmenter la limite si vous avez besoin de factures avec des montants supérieurs à $999 999,99.
Pas de prise en charge native pour l’émission d’avoirs avec Metronome	L’intégration Metronome ne prend pas en charge nativement l’émission d’avoirs (credit memos) dans Stripe. Découvrez comment émettre des avoirs.

INTÉGRATIONS DE FACTURATION

INTÉGRATIONS MARKETPLACE

INTÉGRATIONS FISCALES

INTÉGRATIONS DE PLATEFORME

Facturer avec Stripe

Configurer l’intégration Stripe

Connecter Metronome et Stripe

Connecter Metronome à plusieurs comptes Stripe

Configurer les paramètres globaux d’intégration optionnels

Créer des règles de mapping d’entité optionnelles

Définir la customer billing configuration

Définir la billing configuration du contrat

Ajouter un fournisseur de facturation à un contrat existant

Interagir avec l’intégration Stripe

Suivre les statuts de facture Stripe dans Metronome

Calculer dynamiquement la taxe de vente

Timing du paiement pour les factures `charge_automatically`

Écouter les erreurs

Comment Metronome gère les limitations de Stripe

​Configurer l’intégration Stripe

​Connecter Metronome et Stripe

​Connecter Metronome à plusieurs comptes Stripe

​Configurer les paramètres globaux d’intégration optionnels

​Créer des règles de mapping d’entité optionnelles

​Définir la customer billing configuration

​Définir la billing configuration du contrat

​Ajouter un fournisseur de facturation à un contrat existant

​Interagir avec l’intégration Stripe

​Suivre les statuts de facture Stripe dans Metronome

​Calculer dynamiquement la taxe de vente

​Timing du paiement pour les factures charge_automatically

​Écouter les erreurs

​Comment Metronome gère les limitations de Stripe

Configurer l’intégration Stripe

Connecter Metronome et Stripe

Connecter Metronome à plusieurs comptes Stripe

Configurer les paramètres globaux d’intégration optionnels

Créer des règles de mapping d’entité optionnelles

Définir la customer billing configuration

Définir la billing configuration du contrat

Ajouter un fournisseur de facturation à un contrat existant

Interagir avec l’intégration Stripe

Suivre les statuts de facture Stripe dans Metronome

Calculer dynamiquement la taxe de vente

Timing du paiement pour les factures `charge_automatically`

Écouter les erreurs

Comment Metronome gère les limitations de Stripe