# Planifiez votre migration Mappez vos objets de facturation Stripe sur l’architecture de Metronome, élaborez votre catalogue de produits et choisissez un modèle d’intégration. Avant de migrer vos clients existants vers Metronome, planifiez votre migration : 1. Mappez vos objets de facturation Stripe sur l’architecture de Metronome. 2. Élaborez votre catalogue de produits. 3. Choisissez un modèle d’intégration. ## Before you begin Si ce n’est pas déjà fait, [définissez le périmètre de votre migration](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/scope-your-migration.md). ## Mappage entre les concepts de Stripe et ceux de Metronome Familiarisez-vous avec les objets principaux de Metronome et la façon dont ils correspondent aux concepts de facturation à l’usage de Stripe. ### Objets principaux de Metronome Metronome dissocie la mesure de l’utilisation (ce que vous mesurez) de la tarification (ce que vous facturez). Vous pouvez ainsi modifier votre modèle tarifaire sans avoir à changer l’instrumentation de vos événements, et inversement. Hiérarchie des objets Metronome : Usage Events > Billable Metrics > Products > Rate Cards > Contracts > Invoices. | Concept | Description | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Usage Events (Événements d’utilisation)** | Enregistrements bruts de l’activité du client (par ex. : « le client X a utilisé 1 500 tokens d’entrée sur le modèle gpt-5 ») | | **Billable Metrics (Indicateur de facturation)** | Règles permettant d’agréger les événements en quantités facturables. C’est également à cet endroit que vous définissez les clés de regroupement (des propriétés utilisées pour établir les prix ou afficher les informations sur les factures) | | **Products (Produits)** | Libellés de poste de facture. Pour les produits facturés à l’usage, chaque poste est associé à un seul indicateur de facturation | | **Rate Cards (Grilles tarifaires)** | Un référentiel tarifaire (price book) centralisé attribuant un prix à chaque produit. Une même grille tarifaire peut être partagée entre plusieurs clients | | **Contracts (Contrats)** | Accords propres à chaque client faisant référence à une grille tarifaire, définissant la période de facturation et incluant, le cas échéant, des crédits, des engagements ou des dérogations | | **Packages (Forfaits)** | Regroupez les détails de votre grille tarifaire et de vos contrats dans un forfait réutilisable unique pouvant être appliqué à de nouveaux clients (particulièrement utile pour les parcours PLG et en libre-service) | | **Invoices (Factures)** | Généré automatiquement à chaque période de facturation en fonction de l’utilisation, selon les conditions du contrat | ### Comparaison des concepts de facturation de Stripe et Metronome | Concept de facturation à l’usage classique de Stripe | Concept de Metronome | Description | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Billing Meter](https://docs.stripe.com/api/billing/meter/object.md) | [Billable Metric](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-billable-metrics) | Ces deux éléments définissent des règles d’agrégation. Les indicateurs en streaming prennent en charge SUM, COUNT, MAX et LATEST. Les indicateurs SQL prennent également en charge UNIQUE (comptage distinct). Les clés de regroupement composées permettent une tarification multidimensionnelle. Les clés de regroupement, le type d’agrégation et le filtre de type d’événement ne peuvent pas être modifiés après création. | | [Meter Event](https://docs.stripe.com/api/billing/meter-event/create.md) | [Usage Event (Ingest)](https://docs.metronome.com/api-reference/usage/ingest-events) | Ces deux éléments représentent des enregistrements d’utilisation individuels. Les événements Metronome incluent un `transaction_id` pour la déduplication et prennent en charge des charges utiles avec beaucoup de propriétés. | | [Price (basé sur l’usage)](https://docs.stripe.com/api/prices.md) | [Rate (sur une grille tarifaire)](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-manage-rate-cards) | Un objet Price dans Stripe définit le coût unitaire et le lien avec un compteur. Dans Metronome, un objet Rate définit la tarification d’un produit sur une grille tarifaire. Il prend en charge la tarification échelonnée, la tarification multidimensionnelle et les tarifs spécifiques aux engagements. | | [Product](https://docs.stripe.com/api/products.md) | [Product](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts) | Dans Stripe, les objets Products regroupent les objets Prices. Dans Metronome, chaque objet Product est associé à un objet Billable Metric. Types de Product : Usage, Subscription (frais récurrents), Composite (frais en % sur d’autres produits), Fixed (ponctuel/planifié). | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | [Contract](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts) | Dans Metronome, un objet Contract est plus puissant. Il inclut les références à la grille tarifaire, les engagements, les crédits, les réductions, les dérogations et les calendriers. | | [Credit Grant](https://docs.stripe.com/api/billing/credit-grant/object.md) | [Prepaid Commit or Credit](https://docs.metronome.com/api-reference/contracts/create-a-contract) | Les objets Commits incluent un calendrier de facturation (le client paie à l’avance ou à l’expiration). Les objets Credits représentent des crédits offerts (sans calendrier de facturation). Les deux prennent en charge la priorité, l’expiration et un champ d’application défini au niveau de l’objet Contract. | | [Subscription Schedule](https://docs.stripe.com/api/subscription_schedules.md) | [Avenants contractuels et planification](https://docs.metronome.com/guides/implement-metronome/migrate-amendments-to-edits) | Metronome prend en charge nativement la planification des changements de tarification, des renouvellements et des avenants dans le cadre d’un contrat. | | [Facture](https://docs.stripe.com/api/invoices/object.md) | [Facture](https://docs.metronome.com/guides/invoices/overview) | Metronome génère des factures et les envoie à Stripe pour l’encaissement des paiements. Un délai de grâce par défaut de 24 heures est appliqué après la fin de la période de facturation avant la finalisation. | Pour en savoir plus, consultez la section [Fonctionnement de Metronome avec Stripe](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md). ## Élaborez votre catalogue de produits Utilisez les objets Stripe existants (Meters, Prices et Products) comme base pour élaborer votre catalogue de produits Metronome. Les sections ci-dessous détaillent chaque type d’objet. ### Indicateurs de facturation Metronome propose deux types d’indicateurs de facturation : - **Indicateurs en continu** (recommandé) : agrège les événements en temps réel à mesure qu’ils arrivent. Ce type d’indicateur est recommandé pour la plupart des cas d’usage. - **Indicateurs SQL** : pour les calculs complexes tels que les moyennes quotidiennes, les comptages uniques par période ou les formules pondérées. N’utilisez les métriques SQL que si les indicateurs en continu ne peuvent pas répondre à vos besoins. Principes de conception : - **Si vous utilisez des segments de mesure Stripe** : évaluez si la tarification dimensionnelle de Metronome (clés de regroupement composées) vous permet de consolider plusieurs compteurs Stripe en un nombre réduit d’indicateurs de facturation Metronome. - **Si vous n’utilisez pas de segments** : vos indicateurs de facturation Metronome seront probablement mappés 1:1 à partir de vos compteurs Stripe existants avec le même type d’agrégation. - **Cardinalité** : contactez votre représentant Metronome si la cardinalité d’une clé de regroupement approche de 1 000. Évitez d’ajouter des propriétés à cardinalité élevée (telles que request_id ou des ID non limités) comme clés de regroupement. > Les clés de regroupement, le type d’agrégation et le filtre de type d’événement ne peuvent pas être modifiés après création. Planifiez-les soigneusement avant d’enregistrer votre indicateur de facturation. > > Incluez plus de clés de regroupement que ce dont vous pensez avoir besoin. Vous pouvez toujours ignorer les clés inutilisées, mais il n’est pas possible d’en ajouter rétroactivement. Si vous pensez pouvoir utiliser une dimension pour la tarification ou l’affichage ultérieurement, incluez-la dès maintenant comme clé de regroupement. ### Mappage du type d’agrégation (indicateurs en continu) | Stripe | Metronome | Description | | ----------------------- | --------- | -------------------------------------------------------------------- | | SUM | SUM | Effectue la somme d’une propriété numérique à travers les événements | | COUNT | COUNT | Compte les événements correspondants | | LAST | LATEST | Prend la valeur la plus récente dans la fenêtre | | MAX (hérité uniquement) | MAX | Valeur maximale dans une fenêtre | ### Indicateurs SQL Pour l’agrégation UNIQUE (comptage distinct), utilisez un [indicateur de facturation SQL](https://docs.metronome.com/guides/implement-metronome/core-concepts/billable-metrics-sql-editor). ### Clés de regroupement Les clés de regroupement déterminent ce que vous pouvez tarifer et la façon dont l’utilisation est répartie sur les factures. On peut les considérer comme une clause `GROUP BY` en SQL, qui segmente l’utilisation agrégée en compartiments en fonction de la valeur d’une propriété. Les clés de regroupement permettent les configurations suivantes en aval sur un produit : | Utilisation en aval | Fonctionnement | Exemple | | ----------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Clé de regroupement de tarification | Différents prix par valeur de dimension | `model_name` -> facturer 1,50 USD pour le modèle A, 0,30 USD pour le modèle B | | Clé de regroupement de présentation | Ventilations des éléments de sous-poste de facture (même prix) | `user_id` -> afficher l’utilisation par utilisateur sur la facture | Exemples de clés de regroupement courants : - `model_name` : tarification par modèle (clé de regroupement de tarification) - `region` : tarification par région (clé de regroupement de tarification) - `instance_type` : tarification par GPU/instance (clé de regroupement de tarification) - `user_id` : ventilations de factures par utilisateur, ou facturation par utilisateur via une agrégation unique (clé de regroupement de présentation) - `project_id` : ventilations de factures par projet (clé de regroupement de présentation) Review your Stripe meter segment dimensions. These are your primary candidates for Metronome group keys. Also consider additional properties in your event payload that you’re not currently using for segmentation but might want for future pricing flexibility or invoice presentation. ### Produits Les produits Metronome représentent des offres de services individuelles : | Type | Cas d’usage | Équivalent Stripe | | ----------- | ---------------------------------------------------------------------------------------- | ----------------- | | Utilisation | Tarification variable basée sur la consommation (nécessite un indicateur de facturation) | Tarif à l’usage | | Abonnement | Frais récurrents selon un calendrier (frais de plateforme, licences par utilisateur) | Tarif récurrent | | Composite | Frais en pourcentage sur un groupe d’autres produits | – | | Fixe | Frais ponctuels ou planifiés (utilisés pour les engagements et les crédits) | – | Options de configuration clés sur les produits : - **Clés de regroupement** : attribuez des clés de regroupement de tarification (prix différents selon la dimension) ou des clés de regroupement de présentation (ventilation des factures). Celles-ci doivent être un sous-ensemble des clés de regroupement définies sur l’indicateur de facturation. - **Conversion de quantité** : par exemple, envoyez des tokens individuels mais affichez et facturez par million de tokens sur la facture. - **Conversion d’arrondi** : par exemple, envoyez des secondes, mais arrondissez à la minute la plus proche sur la facture. ### Grilles tarifaires Une grille tarifaire est un modèle de tarification centralisé qui contient les tarifs de tous vos produits. Chaque grille tarifaire est libellée dans une seule monnaie fiduciaire. Créez une seule grille tarifaire comme source de vérité de tarification standard. Lorsque vous mettez à jour les tarifs sur une grille tarifaire, les modifications se propagent à tous les contrats qui s’y réfèrent. Gérez la tarification personnalisée pour des clients spécifiques via des dérogations sur des contrats individuels. Fonctionnalités de la grille tarifaire : - **Tarification dimensionnelle** : si vous utilisez des clés de regroupement de tarification, définissez des tarifs par valeur de dimension (par exemple, model-A à 1,50 USD, model-B à 0,30 USD). - **Tarification échelonnée** : définissez des paliers basés sur le volume pour n’importe quel produit (par exemple, premier million de tokens à 1,00 USD, celui d’après à 0,80 USD). - **Unités de tarification personnalisées** : si vous facturez en crédits ou dans une unité personnalisée plutôt qu’en monnaie fiduciaire, créez une unité de tarification personnalisée sous « Offering (Offre) » puis « Pricing Units (Unités de tarification) » et configurez la conversion sur la grille tarifaire. - **Taux d’engagement** : définissez des taux qui s’appliquent spécifiquement lorsque l’utilisation est imputée sur un engagement. - **Modifications de taux** : modifiez les tarifs en définissant une date de début pour le nouveau tarif. Les modifications sont automatiquement propagées aux contrats qui y font référence. ### Facturation Le [cycle de vie de la facture](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md) de Metronome suit les étapes suivantes : 1. **Brouillon** : accumule l’utilisation tout au long de la période de facturation (visible dans Metronome). 2. **Période de grâce** : période de 24 heures (par défaut) à la fin de la période de facturation avant la finalisation, permettant la prise en compte des données d’utilisation arrivant en retard et de corrections. 3. **Finalisée** : Metronome verrouille la facture après la période de grâce. Aucune modification supplémentaire n’est autorisée. 4. **Envoyée au fournisseur de facturation** : Metronome transfère les factures finalisées à Stripe (crée des objets `InvoiceItem` et une `Invoice` sur le client Stripe). 5. **Payée ou échouée** : Stripe gère l’encaissement (Smart Retries, Radar et les paramètres de nouvelle tentative s’appliquent automatiquement). Principales considérations : - Stripe Tax, Anrok ou Avalara peuvent être appliqués lors de la finalisation de la facture Stripe. - Configurez la méthode d’encaissement (`charge_automatically` ou `send_invoice`) par client. - Gérez l’état du paiement dans le Dashboard Stripe, et non dans Metronome. - Configurez des webhooks pour écouter les états de paiement dans le cas d’engagements conditionnés au paiement. ## Choisissez un modèle d’intégration Metronome prend en charge les [modèles d’intégration](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md) suivants avec Stripe : - **Metronome de manière indépendante** : Metronome gère toute la facturation et le suivi, et transfère les factures finalisées à Stripe pour l’encaissement des paiements. Idéal si vous migrez entièrement depuis Stripe Subscriptions. **Choisissez Metronome de manière indépendante si :** - Toute votre facturation est basée sur l’usage - Vous souhaitez utiliser l’ensemble des fonctionnalités de contrat et d’engagement de Metronome - Vous n’avez pas besoin de Stripe Checkout ou de Payment Links pour l’inscription - **Metronome avec Stripe Subscriptions** : Stripe Subscriptions gère la facturation récurrente et forfaitaire. Metronome gère séparément le suivi et la facturation basée sur l’usage. Les deux solutions créent des factures sur le même client Stripe. **Choisissez Metronome avec Stripe Subscription si :** - Vous avez des frais récurrents à tarif fixe ou par utilisateur sur Stripe Subscriptions - Vous souhaitez conserver Checkout, le portail client et Payment Links pour la facturation qui n’est pas liée à l’utilisation - Vous n’avez besoin de Metronome que pour la composante de facturation à l’usage ## Étapes suivantes Une fois que vous avez défini la portée et élaboré votre migration, [configurez Metronome](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/set-up.md).