Passer au contenu principal
Comprenez comment modifier le nombre de sièges sur un abonnement, surveiller le solde actif et consulter l’historique des modifications.

​
Modifier le nombre de sièges

Une fois qu’un contrat est créé, vous pouvez modifier le nombre de sièges sur l’abonnement à l’aide du point de terminaison edit contract. Le mécanisme pour modifier le nombre de sièges dépend de si vous utilisez le champ quantity pour ajuster le nombre ou la seat_config.

​
Changement de quantité​ pour les abonnements standards et les pools de crédits

Planifiez un changement de la quantité d’un abonnement à l’aide de l’action update_subscription sur le point de terminaison edit contract. Passez soit le nouveau total via quantity, soit la différence par rapport au nombre précédent via quantity_delta. Les mises à jour planifiées avec le même starting_at sont appliquées dans l’ordre où elles sont soumises. Les changements de quantité sont facturés selon les paramètres de proratisation dans la configuration de l’abonnement sur le contrat. Pour les abonnements liés à des crédits récurrents, le changement de quantity libérera également un nouveau solde de crédits. Le montant du solde dépend des paramètres de proratisation et du access_amount sur la configuration du crédit récurrent. Cet appel montre un exemple d’utilisation de /contracts/edit pour modifier le nombre de sièges d’un abonnement : 
{
    "customer_id": "68cd7fb2-235a-4d4d-9ee3-15c49e866884",
    "contract_id": "7f865c1b-1c08-40e8-9c09-b3238fd3b50d",
    "update_subscriptions": [
        {
            "subscription_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "quantity_updates": [
                {
                    "quantity": 3,
                    "starting_at": "2025-04-29T00:00:00.000Z"
                }
            ]
        }
    ]
}

​
Changement de quantité​ pour les abonnements à crédits basés sur les sièges

Au lieu de simplement modifier la quantity, spécifiez les seat_ids qui sont ajoutés ou supprimés de l’abonnement. Ajoutez ou supprimez éventuellement des sièges non attribués. Les factures sont facturées et les crédits sont libérés selon les paramètres des configurations d’abonnement et de crédits récurrents. Voici un exemple de modification du nombre de sièges pour les abonnements à crédits basés sur les sièges : 
{
    "customer_id": "1f79c5c6-400a-4be4-9573-30c667454e4c",
    "contract_id": "2159a5c1-7436-43eb-a46c-7a2e5f030afa",
    "update_subscriptions": [
        {
            "subscription_id": "16de7fa0-b387-44e9-b521-0945db3b8af8",
            "seat_updates": {
                "add_seat_ids": [
                    {
                        "seat_ids": ["customer4@metronome.com"],
                        "starting_at": "2025-12-01T00:00:00Z"
                    }
                ],
                "remove_seat_ids": [
                     {
                         "seat_ids": ["customer2@metronome.com"],
                         "starting_at": "2025-11-15T00:00:00Z"
                     }
                 ],
                 "add_unassigned_seats": [
                     {
                         "quantity": 2,
                         "starting_at": "2025-10-01T00:00:00Z"
                     }
                 ]
            }
        }
    ]
}

​
Supprimer un ID de siège tout en maintenant la quantité totale

Dans certains cas, vos clients peuvent changer qui a accès à un siège. À mesure que des personnes changent de rôle ou quittent leur entreprise, ils peuvent vouloir libérer le siège pour que quelqu’un d’autre l’utilise. Pour ce faire dans Metronome, supprimez l’ID du siège et ajoutez un siège non attribué. Cela garantit que la quantité totale pour l’abonnement reste la même, mais qu’un siège est désormais disponible pour quelqu’un d’autre. Cet exemple supprime un ID de siège et ajoute un siège non attribué dans le même appel : 
{
    "customer_id": "1f79c5c6-400a-4be4-9573-30c667454e4c",
    "contract_id": "2159a5c1-7436-43eb-a46c-7a2e5f030afa",
    "update_subscriptions": [
        {
            "subscription_id": "16de7fa0-b387-44e9-b521-0945db3b8af8",
            "seat_updates": {
                "remove_seat_ids": [
                     {
                         "seat_ids": ["customer1@metronome.com"],
                         "starting_at": "2025-11-15T00:00:00Z"
                     }
                 ],
                 "add_unassigned_seats": [
                     {
                         "quantity": 1,
                         "starting_at": "2025-11-15T00:00:00Z"
                     }
                 ]
            }
        }
    ]
}

​
Surveiller le solde de crédits

Vous pouvez configurer des notifications de seuil sur le solde de crédits pour recevoir des webhooks lorsque le solde du client atteint un certain niveau. Lors de la réception de ces webhooks, vous pouvez restreindre l’accès du client jusqu’à ce qu’il achète un pack de crédits supplémentaires ou que la prochaine période de facturation commence. Cette alerte n’évalue que les crédits au niveau du client ou du contrat — les crédits scopés au siège ne sont pas inclus dans le calcul. Cet appel API montre comment créer une notification de seuil lorsque le client a 10 crédits IA restants à l’aide du point de terminaison /alerts/create. 
{  
    "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",  
    "credit_type_id": "d3cb2827-dcb5-44af-9354-947a7197b9a6",  
    "threshold": 10,  
    "name": "10 AI credits remaining reached",  
    "customer_id": "d8319d6f-8ee0-43a7-b76f-d7587c0a811c"  
}
Pour configurer une notification de seuil pour les crédits et engagements scopés au siège, créez une notification low_remaining_seat_balance_reached à l’aide du point de terminaison /alerts/create. Le paramètre seat_filter, requis dans le corps de la requête lors de la création de cette notification, fournit un champ seat_group_key qui est utilisé pour limiter la portée de la notification aux soldes de sièges associés à des abonnements basés sur les sièges avec un seat_group_key spécifique dans leur configuration seat_config. Cet appel API montre comment créer une notification de seuil lorsqu’un client a 15 crédits IA restants pour n’importe quel siège sur un abonnement avec un seat_group_key de seat_id. 
curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "low_remaining_seat_balance_reached",
    "threshold": 15,
    "name": "15 AI credits remaining reached",
    "credit_type_id": "d3cb2827-dcb5-44af-9354-947a7197b9a6",
    "customer_id": "d8319d6f-8ee0-43a7-b76f-d7587c0a811c",
    "seat_filter": { "seat_group_key": "seat_id" }
  }'
Pour récupérer l’état de l’alerte pour un siège spécifique, utilisez le point de terminaison /customer-alerts/get. Voici un exemple de récupération de l’état de l’alerte pour un siège spécifique : 
curl https://api.metronome.com/v1/customer-alerts/get \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "customer_id": "5cceec38-51fe-4399-8bed-fcb2a8ad1fb7",
        "alert_id": "e9c0d89d-040e-4ffc-91f6-001c6954d7a7"
        "seat_filter": {"seat_group_key": "seat_id", "seat_group_value": "seat123"}
    }'
Utilisez éventuellement le paramètre seat_filter.seat_group_value pour limiter la portée de la notification à un siège spécifique. Voici un exemple de création d’une notification de seuil lorsqu’un client a 5 crédits IA restants pour un siège spécifique sur un abonnement avec un seat_group_key de seat_id et un seat_group_value de seat123. 
curl https://api.metronome.com/v1/alerts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "low_remaining_seat_balance_reached",
    "threshold": 5,
    "name": "5 AI credits remaining reached",
    "credit_type_id": "d3cb2827-dcb5-44af-9354-947a7197b9a6",
    "customer_id": "d8319d6f-8ee0-43a7-b76f-d7587c0a811c",
    "seat_filter": {"seat_group_key": "seat_id", "seat_group_value": "seat123"}
  }'

​
Visualiser l’historique des sièges

Dans le cadre de votre expérience produit, vous pouvez vouloir présenter le changement de quantité de sièges au fil du temps pour offrir de la transparence à votre client :
  • Historique de quantité : pour interroger les modifications de la quantité d’abonnement, utilisez le point de terminaison /getSubscriptionQuantityHistory.
  • Historique des ID de sièges : si vous gérez les sièges à l’aide de la seat_config, vous pouvez interroger l’historique de chaque seat_id à l’aide du point de terminaison /get-subscription-seats-history.

​
Visualiser le solde des sièges

Si vous construisez un modèle de facturation d’abonnement scopé au siège, vous voudrez probablement afficher le solde actif par siège et le solde du siège au fil du temps. Pour interroger ces informations, utilisez le point de terminaison /contracts/seatBalances/list :
  • Solde actuel des sièges : passer le customer_id et le contract_id renverra le balance actuel pour tous les sièges. Passer un seat_id dans le corps de la requête limitera les résultats à un siège individuel.
  • Historique du grand livre des sièges : pour créer une vue qui affiche l’historique des attributions de crédit et de leur consommation associée, passez include_ledgers: true dans le corps de la requête. Passez éventuellement les dates starting_at et ending_before pour filtrer la réponse à une période spécifiée.