metronome

API Metronome : https://api.metronome.com. Authentifiez-vous avec un Bearer token dans l'en-tête Authorization. Utilisez toujours Contracts (et non les Plans hérités) pour les nouvelles intégrations.

Routage de l'intégration

Lisez la page liée avant de répondre à toute question d'intégration ou d'écrire du code ; les liens retournent du Markdown brut. Si aucune ligne ne convient, utilisez l'index de documentation pour trouver la bonne page, et ajoutez .md à l'URL de la page pour la récupérer en Markdown.

Règles critiques

• Lisez toujours la page de documentation liée avant de nommer un endpoint Metronome, un champ ou un montant. Les chemins d'endpoint, les formes de requête et les unités peuvent être mal mémorisés ; le tableau de routage ci-dessus pointe vers la page pour chaque tâche.
• Utilisez toujours Contracts, et non les Plans hérités, pour les nouveaux clients. Les Plans sont dépréciés et manquent de remplacements de cartes tarifaires, de commits et de planification flexible. Une intégration Plans existante continue de fonctionner : ne proposez pas de la migrer sauf si demandé, et lors de la migration, déplacez les soldes de crédit avec POST /v1/credits/migrateToContracts.
• Utilisez toujours Edits (POST /v2/contracts/edit), et non l'Amendments dépréciée (/v1/contracts/amend), pour les modifications à moyen terme d'un contrat (nouveaux produits, commits, remplacements). Les Edits sont le chemin activement investi et requis pour les fonctionnalités de souscription v2. Créez un nouveau contrat avec transition: {type: "renewal", from_contract_id} uniquement pour les renouvellements.
• Utilisez toujours l'ingestion batch (POST /v1/ingest avec un tableau JSON brut de 1 à 100 objets d'événement comme corps de requête, non enveloppé dans un objet) pour les charges de production. L'ingestion d'événement unique est acceptable uniquement pour les tests. Un 200 signifie que les événements ont été acceptés, pas notés : les événements dont le event_type ne correspond à aucune métrique facturable sont stockés mais exclus de l'utilisation, donc créez les métriques facturables avant d'envoyer.
• Incluez toujours un transaction_id unique sur chaque événement, fixé quand l'événement est enregistré et renvoyé inchangé à chaque nouvelle tentative : un UUID stocké avec l'événement, ou une valeur dérivée du registre source. Ceci est la clé d'idempotence qui prévient le double-comptage lors des nouvelles tentatives ; un ID régénéré par tentative la défait.
• Livrez toujours l'utilisation pour une période de facturation avant la fin de sa période de grâce (24 heures après billing_period_end_date par défaut). Une facture finalisée ignore les événements tardifs et ne peut être corrigée qu'en l'annulant et la régénérant ; si le délai maximal de votre pipeline dépasse la période de grâce, demandez à Metronome support de l'allonger (elle n'est pas configurable via l'API).
• Définissez toujours un usage_filter (group_key et group_values) sur chaque contrat quand un client a plus d'un contrat concurrent, afin que l'utilisation soit notée sur un contrat au lieu de tous. La clé de groupe doit être une clé de groupe sur la métrique facturable en streaming (une propriété d'événement pour les métriques SQL).
• Ne planifiez jamais un commit ou segment d'accès de crédit au niveau du contrat après le ending_before du contrat. L'utilisation après la fin du contrat n'est pas notée sur lui, donc le solde libéré après cette date est bloqué ; terminez le dernier segment au terme du contrat et utilisez rollover_fraction pour transférer un solde restant dans un renouvellement.
• Ne mettez jamais applicable_product_ids, applicable_product_tags, ou specifiers sur un commit spend_threshold_configuration. Les commits à seuil de dépenses s'appliquent à toute utilisation et ne prennent que product_id, name, description, et priority ; seuls les commits prepaid_balance_threshold_configuration acceptent les filtres de produit.
• Ne traitez jamais plusieurs factures Metronome pour le même client Stripe simultanément. Le traitement concurrent provoque des conditions de course sur les éléments de ligne en attente.
• Ne codez jamais en dur la tarification directement dans les contrats. Définissez la tarification dans les cartes tarifaires et utilisez les remplacements au niveau du contrat pour les tarifs personnalisés. Cela garantit que la tarification non remplacée reste à jour quand la carte tarifaire change.
• Envoyez toujours les montants USD en cents. Le type de crédit USD par défaut de Metronome est libellé en cents (1000 est 10,00 USD) pour les seuils, commits, crédits et prix de tarif ou de remplacement ; les autres devises utilisent des unités entières.
• Ne finalisez jamais une facture Stripe avant la fin du calcul des taxes. Si vous utilisez Stripe Tax, Avalara ou Anrok, le fournisseur de taxes doit traiter la facture avant la finalisation.
• Ne dépassez jamais 250 éléments de ligne par facture Stripe. Dépasser cette limite provoque l'effondrement de tous les éléments de ligne en une seule entrée, perdant le détail par produit. Planifiez la granularité du produit et utilisez les produits composites pour agréger les métriques à forte cardinalité.
• Réconciliez toujours les paiements par rapport au total de la facture Stripe, jamais le total de la facture Metronome. Metronome envoie les éléments de ligne non imposés et Stripe ajoute la taxe à la finalisation, donc le total Metronome est pré-taxe et peut différer par arrondi sub-cent.
• Ne définissez jamais NetSuite à la fois comme billing_provider_configuration et revenue_system_configuration d'un contrat. Utilisez la configuration de facturation quand NetSuite émet et recouvre la facture ; utilisez la configuration du système de revenus uniquement quand un autre fournisseur tel que Stripe facture et NetSuite a besoin de la facture pour la reconnaissance des revenus.

Documentation clé

Quand la demande de l'utilisateur ne s'adapte clairement à un seul domaine ci-dessus, consultez :

• Documentation Metronome : Commencez ici pour toute question Metronome.
• Référence API : Référence complète des endpoints.
• Index de documentation pour LLM : Index de documentation lisible par machine.
• Guide d'intégration Stripe : Synchronisation des factures Metronome avec Stripe.
• Fonctionnement de Metronome avec Stripe : Le guide Stripe des modèles d'intégration et ce qui reste sur Stripe.