Passer au contenu principal
Aidez les clients à comprendre l’impact financier de leurs actions avant qu’ils ne s’engagent à les entreprendre. Le point de terminaison preview events vous permet de simuler comment des événements affecteraient la facture d’un client sans réellement les traiter ni les facturer.

​
Pourquoi prévisualiser les coûts ?

La transparence sur les coûts renforce la confiance et permet aux clients de prendre des décisions éclairées. Les scénarios courants comprennent :
  • Prévisualisation du coût d’opérations gourmandes en ressources : montrez aux utilisateurs combien coûtera une tâche de calcul ou de traitement des données avant de confirmer son exécution
  • Planification budgétaire : aidez les clients à prévoir les coûts pour des modes d’utilisation planifiés grâce à des calculateurs de coûts interactifs
  • Analyse hypothétique : laissez les clients explorer différents scénarios d’utilisation pour optimiser leurs dépenses

​
Fonctionnement de la prévisualisation des coûts

Le point de terminaison preview events évalue les événements par rapport à la configuration réelle du contrat d’un client, y compris toute la complexité tarifaire :
  • Tarification par paliers : applique correctement les remises sur volume et les transitions entre paliers
  • Commits et credits : indique quelle utilisation est couverte par les soldes de commits et de credits et ce qui déborde en surutilisation
  • Allotissements gratuits : tient compte de l’utilisation incluse dans le contrat
  • Plusieurs produits : calcule les coûts pour tous les produits du contrat

​
Modes de prévisualisation

Il existe deux manières différentes d’évaluer les événements de prévisualisation :

​
Mode merge

Combine les événements de prévisualisation avec l’utilisation existante du client pour la période de facturation. Utilisez-le pour montrer l’impact incrémental sur les coûts. Exemple : un client a utilisé 99 appels API ce mois-ci (avec 100 gratuits). La prévisualisation de 5 appels en mode merge affiche 1 appel gratuit et 4 facturables.

​
Mode replace

Évalue uniquement les événements de prévisualisation, en ignorant l’utilisation existante. Utilisez-le pour des scénarios hypothétiques « table rase ». Exemple : montrer le coût mensuel total si un client n’avait effectué que les actions spécifiques de la prévisualisation.

​
Configurer une prévisualisation des coûts

​
Exemple de base

Prévisualisez comment 100 heures de calcul affecteraient la facture d’un client : 
curl --request POST \
  --url https://api.metronome.com/v1/customers/{customer_id}/previewEvents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "events": [
      {
        "event_type": "compute_usage",
        "timestamp": "2025-11-15T10:00:00Z",
        "properties": {
          "compute_hours": "100",
          "instance_type": "gpu-large"
        }
      }
    ],
    "mode": "merge"
  }'

​
Structure de la réponse

Le point de terminaison renvoie des factures provisoires indiquant les coûts calculés : 
{
  "data": [
    {
      "id": "68e0bc1c-a8ec-5765-856b-f896285b4cdb",
      "issued_at": "2025-12-02T12:00:00+00:00",
      "start_timestamp": "2025-11-01T00:00:00+00:00",
      "end_timestamp": "2025-12-01T00:00:00+00:00",
      "customer_id": "46b2c479-6202-4db6-b392-5a156a9dd5c8",
      "customer_custom_fields": {
        "bill_customer_id": "0du01JDIRIUDQKDS6wm2"
      },
      "type": "USAGE",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "status": "DRAFT",
      "total": 49000,
      "external_invoice": null,
      "contract_id": "688d9619-bd2c-42db-8dcb-288f02f741df",
      "contract_custom_fields": {},
      "line_items": [
        {
          "product_id": "c2ab408b-d212-4dca-a99b-f2b450abad45",
          "product_type": "UsageProductListItem",
          "product_custom_fields": {
            "org_id": "prod_NbZryAoW6ugALt"
          },
          "product_tags": [
            "compute"
          ],
          "name": "GPU Compute Hours",
          "type": "usage",
          "total": 0,
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "starting_at": "2025-11-01T00:00:00+00:00",
          "ending_before": "2025-12-01T00:00:00+00:00",
          "netsuite_item_id": "f2b4-50ab-ad45",
          "unit_price": 4900,
          "quantity": 10
        }
      ],
      "custom_fields": {},
      "billable_status": "billable"
    }
  ]
}
Pour les clients ayant plusieurs contrats actifs, le point de terminaison renvoie des factures distinctes pour chacun : 
{
  "data": [
    {
      "contract_id": "contract-1-id",
      "total": 50000,
      // ... invoice details for contract 1
    },
    {
      "contract_id": "contract-2-id",
      "total": 25000,
      // ... invoice details for contract 2
    }
  ]
}

​
Déduplication des événements

Le point de terminaison de prévisualisation suit la même logique de déduplication que le point de terminaison d’ingestion :
  • Les événements ayant des valeurs transaction_id identiques transmis dans la même charge utile de requête sont dédupliqués entre eux
  • Les événements ayant des valeurs transaction_id identiques à celles transmises à /ingest au cours des 34 derniers jours sont également dédupliqués

​
Bonnes pratiques et limitations

​
Considérations de performance

Le point de terminaison a une limite de débit de 8 RPS par client et n’est pas adapté à la validation en temps réel de chaque événement. Envisagez ces stratégies :
  • Mettre en cache les résultats de prévisualisation : lorsque vous affichez des calculs répétés pour des modes d’utilisation similaires, mettez les résultats en cache
  • Regrouper plusieurs événements : prévisualisez plusieurs événements dans une seule requête plutôt que de faire des appels séparés

​
Conseils de précision

  • Incluez toutes les propriétés d’événement pertinentes qui affectent la tarification
  • Testez à la fois les modes merge et replace pendant le développement

​
Limitations

  • Les clients utilisant des billable metrics basées sur SQL ne peuvent pas utiliser ce point de terminaison. Si des SQL BMs sont présentes sur la facture client évaluée lors de la transmission d’événements à prévisualiser, le point de terminaison renverra une erreur 400.