Démarrage rapide de l'API

​

Prérequis

• Un compte sandbox Metronome (inscrivez-vous ici)
• Votre jeton d’API sandbox Metronome (Connexions → Jetons d’API et webhooks dans le tableau de bord)

​

Environnements et authentification

​

Étape 1 : Comprendre comment les pièces s’assemblent

• Événements d’utilisation — Enregistrements bruts de l’activité du client envoyés à Metronome (par exemple, « le client X a utilisé 1 500 tokens d’entrée sur le modèle gpt-5 à l’horodatage Z »)
• Métriques facturables — Règles qui agrègent vos événements en quantités facturables (par exemple, « somme de la propriété input_tokens pour les événements de type llm_request »). C’est également là où vous définissez les clés de groupe — les propriétés que vous utiliserez pour tarifer ou afficher sur les factures.
• Produits — Postes nommés sur une facture.
• Cartes tarifaires — Un livre de prix centralisé attribuant un prix à chaque produit. Une seule carte tarifaire peut être partagée entre de nombreux clients, ce qui facilite le déploiement des mises à jour de tarification.
• Contrats — Accords spécifiques au client référençant une carte tarifaire, définissant la période de facturation et incluant optionnellement des crédits, engagements ou remplacements.
• Packages — Encode votre carte tarifaire et les détails du contrat dans un seul package à appliquer à de nouveaux clients.
• Factures — Générées automatiquement à chaque période de facturation en fonction des frais récurrents et de l’utilisation d’un client, tarifées par rapport au contrat.

1. Une métrique facturable
2. Un produit
3. Une carte tarifaire avec des taux pour chaque produit
4. Un client
5. Un contrat reliant le client à la carte tarifaire

​

Étape 2 : Concevoir votre schéma d’événements

{
  "transaction_id": "2026-03-09T14:30:00Z_req_abc123",
  "customer_id": "your-customer-uuid-in-metronome",
  "event_type": "llm_request",
  "timestamp": "2026-03-09T14:30:00Z",
  "properties": {
    "model": "gpt-5",
    "input_tokens": "1500",
    "output_tokens": "350",
    "provider": "openai",
    "region": "us-east-1",
    "user_id": "user_8f3a",
    "cost": "0.0042"
  }
}

​

Champs requis

• transaction_id — Unique par événement pour l’idempotence. Si le même transaction_id est envoyé deux fois, Metronome déduplique. Conseil : combinez horodatage + ID de requête.
• customer_id — UUID du client Metronome, ou un ingest_alias configuré sur le client (afin que vous puissiez utiliser votre propre ID interne).
• event_type — Chaîne reliant cet événement à une métrique facturable. Doit correspondre exactement aux in_values du event_type_filter de la métrique facturable.
• timestamp — Format ISO 8601. Doit être dans les 34 derniers jours (fenêtre de rétrodatation de Metronome). Les événements futurs sont rejetés.

​

Propriétés (dépendantes de la métrique)

• properties — Paires clé-valeur. Toutes les valeurs doivent être des chaînes (même les nombres) — Metronome utilise des décimales de précision arbitraire en interne pour éviter les problèmes de virgule flottante. Metronome prend également en charge jusqu’à 2 000 propriétés par événement.

1. Agrégation — La valeur que vous additionnez, comptez ou maximisez (par exemple, input_tokens, duration_seconds)
2. Clés de groupe — Dimensions pour la tarification (par exemple, model, region) ou l’affichage de facture (par exemple, user_id, project_id). Doivent être définies sur la métrique facturable au préalable.
3. Métadonnées — Contexte pour les clients, analyse COGS, ou anticipation (par exemple, provider, cost, endpoint)

​

Schémas d’événements courants

​

Étape 3 : Créer une métrique facturable

​

Exemple — Compter les appels API (simple) :

curl -X POST https://api.metronome.com/v1/billable-metrics/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "aggregation_type": "count",
    "event_type_filter": {
      "in_values": ["api_call"]
    }
  }'

​

Exemple — Somme des tokens avec clés de groupe :

curl -X POST https://api.metronome.com/v1/billable-metrics/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Input Tokens",
    "aggregation_type": "sum",
    "aggregation_key": "input_tokens",
    "event_type_filter": {
      "in_values": ["llm_request"]
    },
    "property_filters": [
      { "name": "model", "exists": true },
      { "name": "input_tokens", "exists": true },
      { "name": "user_id", "exists": true }
    ],
    "group_keys": [["model"], ["user_id"]]
  }'

​

Types d’agrégation

• count — Nombre d’événements correspondants (appels API, requêtes)
• sum — Somme d’une propriété numérique (tokens, octets, secondes)
• max — Valeur maximale dans une fenêtre (stockage de pointe, connexions simultanées)

​

Clés de groupe

​

Métriques facturables SQL

SELECT count(DISTINCT properties.user_id) as value,
       properties.region
FROM events
WHERE event_type = 'api_request'
GROUP BY properties.region

​

Étape 4 : Créer un produit

​

Exemple — Produit d’utilisation avec clés de groupe :

curl -X POST https://api.metronome.com/v1/contract-pricing/products/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Input Tokens",
    "type": "usage",
    "billable_metric_id": "<your-billable-metric-id>",
    "pricing_group_key": ["model"],
    "presentation_group_key": ["user_id"]
  }'

​

Types de produits

• usage — Tarifé de manière variable en fonction de l’utilisation du client (nécessite une métrique facturable)
• subscription — Frais récurrents selon un calendrier (frais de plateforme, licences de sièges)
• composite — Frais en pourcentage sur un produit d’utilisation
• fixed — Frais ponctuels ou planifiés (engagements, crédits, frais ponctuels)

​

Attribution des clés de groupe

​

Étape 5 : Créer une carte tarifaire

​

Créer la carte tarifaire :

curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard Pricing"}'

​

Ajouter des taux :

curl --request POST \
  --url https://api.metronome.com/v1/contract-pricing/rate-cards/addRates \
  --header 'Authorization: Bearer $METRONOME_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "rates": [
    {
      "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "entitled": true,
      "rate_type": "FLAT",
      "price": 100,
      "pricing_group_values": {
        "region": "us-west-2",
        "cloud": "aws"
      }
    },
    {
      "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "entitled": true,
      "rate_type": "FLAT",
      "price": 120,
      "pricing_group_values": {
        "region": "us-east-2",
        "cloud": "aws"
      }
    }
  ]
}
'

​

Ajouter une tarification dimensionnelle (une entrée par valeur) :

curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/rates/add \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_card_id": "<your-rate-card-id>",
    "product_id": "<your-product-id>",
    "starting_at": "2026-03-01T00:00:00Z",
    "rate_type": "flat",
    "price": 1.50,
    "entitled": true,
    "pricing_group_values": {
      "model": "gpt-5"
    }
  }'

​

Fonctionnalités supplémentaires

• Tarification par paliers — Paliers basés sur le volume via le champ tiers sur une entrée de taux
• Unités de tarification personnalisées — Créez sous Offre → Unités de tarification dans l’interface utilisateur, puis référencez le credit_type_id sur la carte tarifaire pour la facturation basée sur les crédits. En savoir plus →
• Taux d’engagement — Taux qui s’appliquent spécifiquement au tirage sur les engagements prépayés

​

Étape 6 : Créer un client et un contrat

​

Créer un client :

curl -X POST https://api.metronome.com/v1/customers/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Customer",
    "ingest_aliases": ["my-internal-customer-id"]
  }'

​

Créer un contrat :

curl -X POST https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<your-customer-id>",
    "rate_card_id": "<your-rate-card-id>",
    "starting_at": "2026-03-01T00:00:00Z",
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    }
  }'

"billing_provider_configuration": {
  "billing_provider": "stripe",
  "delivery_method": "direct_to_billing_provider"
}

​

Étape 7 : Envoyer vos premiers événements

curl -X POST https://api.metronome.com/v1/ingest \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{
    "transaction_id": "test-001",
    "customer_id": "<your-customer-id>",
    "event_type": "llm_request",
    "timestamp": "2026-03-09T12:00:00Z",
    "properties": {
      "model": "gpt-5",
      "input_tokens": "1500",
      "user_id": "user_1"
    }
  },
  {
    "transaction_id": "test-002",
    "customer_id": "<your-customer-id>",
    "event_type": "llm_request",
    "timestamp": "2026-03-09T12:01:00Z",
    "properties": {
      "model": "gpt-5-mini",
      "input_tokens": "800",
      "user_id": "user_2"
    }
  }]'

​

Comportements importants

• Une réponse 200 signifie que les événements ont été acceptés pour ingestion. Vérifiez le corps de la réponse pour les erreurs par événement.
• Notez que s’il n’y a pas de métrique facturable correspondante pour l’event_type ou si les propriétés requises ne sont pas incluses, les événements sont stockés mais peuvent ne pas apparaître dans les calculs d’utilisation. Assurez-vous de créer les métriques facturables avant d’envoyer des événements s’ils sont nécessaires pour la tarification.
• Les événements peuvent être rétrodatés jusqu’à 34 jours. Les événements avec des horodatages futurs sont rejetés.
• transaction_id est utilisé pour la déduplication. Envoyer le même ID deux fois ne facturera pas deux fois.
• Seuls les événements du point de terminaison ingest sont mesurés. Les appels API pour gérer les clients, contrats, etc. ne sont pas facturables.

​

Vérifier vos événements

​

Dépannage

1. Cliquez sur l’événement sur la page Événements — vérifiez qu’il correspond à une BM et à un client.
2. Vérifiez la réponse de l’API de votre appel ingest pour les erreurs par événement.
3. Si les événements correspondent à une BM + client mais n’apparaissent pas sur la facture : les valeurs de clés de groupe de tarification dans l’événement ne correspondent probablement à aucun taux sur la carte tarifaire. Par exemple, "model": "gpt-5" vs "model": "gpt5" (trait d’union manquant) échouera silencieusement à la tarification.
4. Vérifiez votre jeton d’API est pour le sandbox (pas la production, ou vice versa).

​

Étape 8 : Vérifier votre facture

1. Brouillon — Accumule l’utilisation tout au long de la période de facturation (visible dans Metronome)
2. Finalisé — Verrouillé à la fin de la période de facturation. Il y a une période de grâce de 24 heures à la fin de la période de facturation avant que les factures ne soient finalisées pour apporter toute modification nécessaire à une facture.
3. Envoyé au fournisseur de facturation — Si Stripe est connecté, poussé dans environ une heure après la finalisation. Statut de paiement géré dans le tableau de bord de Stripe.
4. Payé / Échoué — Recouvrement géré par votre fournisseur de facturation

​

Prêt pour plus ?

• Tableaux de bord client intégrables — Visibilité en libre-service de l’utilisation pour vos clients
• Webhooks — Cycle de vie des factures, alertes de solde, événements de paiement
• Alertes et notifications — Seuils de dépense, notifications de solde
• Crédits et engagements — Soldes prépayés, engagements entreprise
• Intégration Stripe — Recouvrement automatisé des paiements
• Reconnaissance des revenus — ASC 606 / IFRS 15
• Liste de vérification de production — Quand vous êtes prêt à passer en production (nouveau jeton d’API, même URL de base, clés Stripe live)