Passer au contenu principal
Utilisez la facturation par seuil de solde prépayé pour activer un modèle de credits prépayés pour vos produits. Ce modèle de facturation exige que les clients paient leur utilisation avant d’utiliser le produit et qu’ils conservent un solde positif pour continuer à accéder au produit. Les credits prépayés sont modélisés en tant que commits dans Metronome. Les seuils de solde prépayé fonctionnent avec les monnaies fiat (telles que USD) et les custom pricing units (tels que des tokens ou des credits). Vous pouvez ainsi configurer l’auto recharge pour les clients dont les soldes sont libellés en custom pricing units, et pas seulement en monnaie fiat. Les seuils de solde prépayé permettent :
  • Auto recharge : recharge automatiquement le solde d’un client lorsqu’il descend au threshold_amount
  • Achat manuel : achetez manuellement des commits pour les clients qui ne souhaitent pas activer l’auto recharge
  • Payment gating : conditionnez la libération du solde du commit, qu’il provienne d’une auto recharge ou d’un achat manuel, à l’encaissement réussi du paiement

​
Configurer l’auto recharge avec des seuils de solde

La configuration de l’auto recharge du solde du client sur un contrat garantit qu’il ne perdra jamais l’accès au produit.

​
Créer un contrat avec des seuils de solde

Lorsque vous créez un contrat dans Metronome, vous pouvez configurer en option une prepaid_balance_threshold_configuration. Cette configuration définit :
  • Le threshold_amount pour le contrat du client : le niveau de solde auquel un client est rechargé.
    • Remarque : lors de l’évaluation de l’atteinte du threshold_amount, Metronome prend en compte le solde total de tous les commits et credits au niveau du contrat et du client. Les credits scopés au niveau seat individuel ne sont pas inclus dans ce calcul.
  • Le recharge_to_amount : le solde auquel le client est remonté après le déclenchement d’une recharge.
  • Un payment_gate_config : configurez si la libération du solde est conditionnée au paiement et quelle passerelle utiliser.
    • Sélectionnez EXTERNAL si vous utilisez une passerelle que Metronome ne prend pas actuellement en charge.
    • Si vous utilisez Stripe, configurez PAYMENT_TYPE pour déterminer si le paiement est envoyé sous forme de facture via Stripe Billing ou directement sous forme de paymentIntent à la passerelle de paiement Stripe.
    • Si vous utilisez Stripe, sélectionnez votre fournisseur de taxes existant.
  • Si la configuration est activée (is_enabled). Si un paiement échoue et que le payment gating est activé, cela passe à false.
CONFIGURER LA FACTURATIONSi vous utilisez Stripe comme passerelle de paiement, assurez-vous qu’une configuration de facturation Stripe valide est définie sur le contrat. De plus, définissez is_enabled à true si vous souhaitez que Metronome évalue immédiatement le contrat après sa création.
De plus, les utilisateurs peuvent éventuellement configurer un discount_config sur la prepaid_balance_threshold_configuration. Cela appliquera une remise au montant facturé au client selon un pourcentage, le montant de la facture étant réduit de X % par rapport au montant d’accès accordé :
  • fraction : la remise appliquée au montant de la facture, représentée sous forme de fraction
  • cap : éventuellement, plafonnez les achats remisés jusqu’à un amount. Le montant est suivi via un spend tracker. Une fois que la dépense accumulée atteint ce plafond, les nouvelles recharges ne seront plus remisées pendant le reste de la période définie dans le spend tracker.
REMISES AVEC CPUSLors de l’utilisation de la facturation par seuils avec des CPUs, le montant du calendrier de facturation est calculé via le tarif de surutilisation. Par exemple, si le taux de conversion entre AI credits et USD était de 2:1, alors une recharge de 100 AI credits coûtera 50 USD. Si une remise de 10 % était définie sur la configuration, les 100 AI credits coûteraient maintenant 45 USD.
Créez des contrats avec des seuils de solde prépayé dans l’application Metronome ou en utilisant l’API Metronome. 
{  
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",  
    "rate_card_id": "a7bc3775-b651-46b6-b7e4-d225a7e55c4c",  
    "starting_at": "2025-05-01T00:00:00.000Z",  
    "billing_provider_configuration": {  
        "billing_provider_configuration_id": "0d40d6ef-6a79-45c2-a716-13eed27a9c8d"  
    },  
    "prepaid_balance_threshold_configuration": {  
        "commit": {  
            "product_id": "d6be3bf4-1669-40c9-a8b1-388bb167ab16",  
            "name": "prepaid_commit",  
            "description": "hello_its_me_im_in_california_dreaming"  
        },  
        "is_enabled": true,  
        "payment_gate_config": {  
            "payment_gate_type": "STRIPE",  
            "stripe_config": {  
                "payment_type": "PAYMENT_INTENT"  
            }  
        },  
        "threshold_amount": 500,  
        "recharge_to_amount": 2100,
        "discount_config": {
          "fraction": 0.9
        }
    }  
}
MINIMUMS DE RECHARGELors de la configuration de l’auto recharge, le recharge_threshold a une valeur minimale de 5 ,etle‘rechargetoamount‘doittoujourse^treaumoins10, et le `recharge_to amount` doit toujours être au moins 10 supérieur à votre seuil. Par exemple, si votre seuil est de 10 ,votre‘rechargetoamount‘doite^tred′aumoins20, votre `recharge_to_amount` doit être d'au moins 20 .Ces minimums s’appliquent que le solde soit libellé en monnaie fiat ou en custom pricing unit. Lors de l’utilisation de custom pricing units, le seuil et les montants de recharge sont évalués dans la custom pricing unit et convertis en monnaie fiat à l’aide du taux de conversion défini sur la rate card du client.

​
Auto recharge avec custom pricing units

Les seuils de solde prépayé prennent en charge les custom pricing units en plus des monnaies fiat. Lorsqu’un contrat client utilise une custom pricing unit (telle que des tokens ou des AI credits), le threshold_amount et le recharge_to_amount sont exprimés dans cette custom pricing unit. Metronome convertit le montant de la recharge en monnaie fiat à l’aide du taux de conversion défini sur la rate card lors du traitement du paiement. Par exemple, considérez une plateforme IA qui tarifie l’utilisation dans une custom pricing unit appelée « AI Tokens », où 1 AI Token = 0,10 $ USD :
  • Le contrat du client a un solde prépayé de 500 AI Tokens
  • Vous définissez un threshold_amount de 50 AI Tokens et un recharge_to_amount de 500 AI Tokens
  • Lorsque le solde du client tombe à 50 AI Tokens, Metronome initie une auto recharge
  • Metronome crée un commit pour 450 AI Tokens (la différence pour atteindre 500) et facture au client 45,00 USD(450×0,10USD (450 × 0,10) via la passerelle de paiement configurée
Le taux de conversion défini sur la rate card détermine comment le montant de la custom pricing unit correspond au montant facturé en monnaie fiat. Pour apprendre à configurer des custom pricing units et configurer les taux de conversion sur une rate card, voir Définir des devises et des custom pricing units.

​
Mettre à jour le seuil de solde prépayé du contrat

Mettez à jour ou ajoutez une prepaid_balance_threshold_configuration en modifiant le contrat. Par exemple, vous pouvez mettre à jour le threshold_amount sur un contrat. Notez que ces changements prennent effet immédiatement et que Metronome force une évaluation du solde actuel du client à chaque modification de configuration. Modifiez les contrats dans l’application Metronome ou avec l’API Metronome. Cet appel d’API ajoute un seuil de solde prépayé à un contrat : 
{  
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",  
    "contract_id": "e066a32a-3b59-4d07-a91f-a9e084903d45",  
    "update_prepaid_balance_threshold_configuration": {  
        "threshold_amount": 600,  
        "recharge_to_amount": 2700  
    }  
}

​
Exclure des soldes des calculs de seuil

Par défaut, Metronome compte tous les commits et credits prépayés dans le solde disponible d’un contrat lors de l’évaluation de l’atteinte d’un seuil (à l’exception des commits et credits scopés à un seat, qui sont toujours exclus). Utilisez les threshold balance specifiers pour restreindre davantage les soldes qui comptent pour le seuil. C’est utile lorsqu’un contrat contient des commits ou des credits qui servent à des fins différentes et que vous ne souhaitez pas que tous soient pris en compte dans les décisions de recharge. Metronome ne déclenchera une recharge que lorsque les soldes correspondant à votre specifier tomberont sous le threshold_amount configuré. Par exemple, considérez une société de bases de données qui propose son produit principal selon un modèle de credits prépayés avec auto top-up activé. La société lance un produit IA adjacent et souhaite donner à tous les clients 10 decreditsd′essaispeˊcifiquesauproduitpourlenouveauproduit.Sansconfiguration,Metronomecomptetouslessoldespreˊpayeˊs—ycomprislescreditsd′essaiIA—lorsdel′eˊvaluationdudeˊclenchementd′unerecharge.Celasignifiequ′unclientavecunthresholdamountde15de credits d'essai spécifiques au produit pour le nouveau produit. Sans configuration, Metronome compte tous les soldes prépayés — y compris les credits d'essai IA — lors de l'évaluation du déclenchement d'une recharge. Cela signifie qu'un client avec un threshold amount de 15 ayant 10 decreditsgeˊneˊrauxet10de credits généraux et 10 de credits d’essai IA a un solde combiné de 20 $, ce qui ne déclenche pas de top-up même si le client est à court de ses credits généraux. Pour s’assurer que le top-up se déclenche en fonction du solde de credits général uniquement, effectuez un seul appel API pour modifier le contrat afin d’introduire le nouveau credit d’essai IA avec un custom field (credit_type: ai_trial) et exclure ce tag du calcul du solde de threshold billing. 
{  
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",  
    "contract_id": "e066a32a-3b59-4d07-a91f-a9e084903d45",  
    "update_prepaid_balance_threshold_configuration": {  
        "threshold_balance_specifiers": [{
            "exclude": [{
                "custom_field_filters": [{
                    "entity": "ContractCreditOrCommit",
                    "key": "credit_type",
                    "value": "ai_trial"
                  }]
              }]
          }]
    },
    "add_credits": [
    {
      "product_id": "ai-trial-product-id",
      "access_schedule": {
        "schedule_items": [
          {
            "amount": 1000,
            "starting_at": "2025-05-01T00:00:00.000Z",
            "ending_before": "2025-06-01T00:00:00.000Z"
          }
        ]
      },
      "custom_fields": {
        "credit_type": "ai_trial"
      },
      "priority": 1
    }
  ]
}
Lorsque plusieurs objets custom_field_filters sont spécifiés dans la condition d’exclusion du threshold balance specifier, Metronome exclut tout solde qui correspond à au moins un des filtres (logique OR). Par exemple, vous pouvez vouloir exécuter plusieurs credits d’essai. L’appel suivant à editContract exclut à la fois les commits et credits étiquetés avec credit_type: ai_trial OU les commits et credits étiquetés avec credit_type: june_product_launch_trial. 
{  
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",  
    "contract_id": "e066a32a-3b59-4d07-a91f-a9e084903d45",  
    "update_prepaid_balance_threshold_configuration": {  
        "threshold_balance_specifiers": [{
            "exclude": [{
                "custom_field_filters": [{
                    "entity": "ContractCreditOrCommit",
                    "key": "credit_type",
                    "value": "ai_trial"
                  }],
                "custom_field_filters": [{
                    "entity": "ContractCreditOrCommit",
                    "key": "credit_type",
                    "value": "june_product_launch_trial"
                  }]
              }]
          }]
    }
}
Si plusieurs paires clé-valeur de custom field sont spécifiées dans un même tableau custom_field_filters, les soldes ne sont exclus que lorsqu’ils correspondent à toutes les paires clé-valeur du filtre (logique AND). Par exemple, l’appel suivant n’exclurait que les commits et credits ayant à la fois les custom fields credit_type: ai_trial ET is_active: true. Notez que vous ne pouvez pas répéter la même clé de custom field dans un seul custom field filter. 
{  
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",  
    "contract_id": "e066a32a-3b59-4d07-a91f-a9e084903d45",  
    "update_prepaid_balance_threshold_configuration": {  
        "threshold_balance_specifiers": [{
            "exclude": [{
                "custom_field_filters": [
                  {
                    "entity": "ContractCreditOrCommit",
                    "key": "credit_type",
                    "value": "ai_trial"
                  },
                  {
                    "entity": "ContractCreditOrCommit",
                    "key": "is_active",
                    "value": "true"
                  }
                ]
              }]
          }]
    }
}

​
Cycle de vie de la facturation par seuil de solde prépayé

Pour tirer le meilleur parti de la facturation par seuil de solde prépayé, prenez en compte son cycle de vie : les actions que Metronome entreprend et celles que vous pourriez avoir à entreprendre.

​
1. Facturer le montant du seuil de solde prépayé (Metronome)

Une fois configurée, Metronome évalue le solde restant disponible pour le client sur le contrat pour déterminer quand le threshold_amount est atteint. Si le payment_gate_config est défini sur Stripe, Metronome tente de facturer le client dans Stripe. Si le paiement réussit, Metronome crée un commit du montant qui recharge le client jusqu’au recharge_to_amount.

​
2. Gérer les notifications (vous)

Metronome déclenche trois types de notifications webhook pour la facturation par seuil de solde prépayé :
  • payment_gate.threshold_reached lorsque le client atteint son seuil.
  • payment_gate.payment_status après qu’un paiement a été tenté. Le statut de ce paiement, paid ou failed, est indiqué dans le champ payment_status.
  • payment_gate.payment_pending_action_required si une intervention est requise pour traiter le paiement.
Votre point de terminaison webhook doit être configuré pour gérer ces notifications en conséquence.

​
3. Gérer les paiements échoués (vous)

Si un paiement échoue, vous recevez un payment_gate.payment_status avec la valeur failed. De plus, le champ is_enabled du contrat est défini sur false. Vous devez vous attendre à voir une facture annulée dans Metronome et Stripe pour cette transaction. À ce stade, vous devez assurer le suivi auprès de votre client directement ou en créant un workflow automatisé déclenché par cette notification webhook. Une fois prêt à retenter le paiement, définissez le champ is_enabled du contrat sur true. Cela force le contrat à être évalué par rapport au threshold_amount, ce qui entraîne une nouvelle tentative de paiement.
Pas de relances automatiquesMetronome ne retente pas automatiquement les paiements échoués (car toute relance automatique échouerait également).

​
Utiliser une passerelle de paiement externe

Si vous utilisez l’option EXTERNAL pour payment_gate_type, vous êtes responsable de faciliter le paiement et d’informer Metronome de la réponse. Suivez ce workflow :
  1. Définissez la configuration de seuil de solde prépayé avec payment_gate_type défini sur EXTERNAL.
  2. Écoutez payment_gate.external_initiate qui indique que Metronome est prêt à recevoir le résultat du paiement.
  3. Enregistrez le workflow_id — vous en avez besoin pour libérer le commit.
  4. Facturez le client dans la passerelle de paiement de votre choix.
  5. Appelez commits/threshold-billing/release pour soit libérer le commit en cas de paiement réussi, soit annuler le commit en cas d’échec.