Passer au contenu principal
Un package est un ensemble réutilisable et relatif au temps de conditions contractuelles. Les packages vous permettent de maintenir une seule grille tarifaire tout en prenant en charge une variété de plans tarifaires, pour optimiser simplicité et flexibilité. Définissez un package dans Metronome pour encoder un ensemble standardisé de conditions contractuelles une seule fois, puis provisionnez de nombreux clients avec ce même package, ce qui facilite la gestion de cohortes ayant des structures contractuelles identiques. Utilisez les packages pour modéliser des mouvements pay-as-you-go standard avec des plans Good/Better/Best (voir le guide Pay as you go) afin de provisionner les clients de manière cohérente et évolutive.

​
Prérequis

Avant de créer un package, vous devez disposer :

​
Créer un package

Créez des packages en utilisant le point de terminaison /packages/create. La création de package est presque identique à la création de contrat, avec les exceptions suivantes :
  • Les packages sont indépendants du client. Ne passez pas de customer_id ni de configuration de facturation client lors de la création d’un package
  • Les packages sont relatifs au temps. Définissez starting_at_offset et duration pour des durées relatives au lieu de dates starting_at et ending_before.
  • Les packages prennent en charge les alias. Comme les alias de grille tarifaire, les packages prennent en charge des alias qui aident à gérer programmatiquement les déploiements de nouveaux packages.
Considérez l’exemple d’une entreprise d’IA, Gnome AI, avec un Starter Plan qui comprend :
  • un crédit récurrent d’inscription de 10 $ appliqué aux jetons d’entrée et de sortie pour les 3 premiers mois
  • des frais d’abonnement mensuels de 10 $
  • des tarifs standard pour les jetons d’entrée et de sortie
Pour créer ce package dans l’application Metronome, allez dans Offering → Packages → Add package.
  1. Donnez au package un Name ayant du sens en interne (par exemple, Starter Plan - October 2025)
  2. Ajoutez une Description facultative (par exemple, Standard Starter Plan pricing as of October 1, 2025)
  3. Optionnellement Add aliases. Les alias peuvent être utilisés à la place de l’ID de package généré par Metronome lors du provisionnement de contrats via l’API. Apprenez-en plus sur la façon dont les alias vous aident à lancer de nouveaux tarifs tout en maintenant votre infrastructure d’intégration.
  4. Set billing terms. Définissez la durée par défaut du contrat, les conditions de paiement net et le fournisseur de facturation.
  5. Choose a rate card. Cela déterminera les tarifs utilisés pour chaque package.
  6. Add terms. Ajoutez des engagements, crédits, abonnements, facturation par seuil ou charges planifiées au package. Tous les contrats provisionnés avec un package contiendront les conditions définies. Pour le Starter Plan ci-dessus, ajoutez un crédit d’inscription récurrent et des frais d’abonnement mensuels.
  7. Add overrides. Ajoutez des remplacements à tout tarif associé à la grille tarifaire sélectionnée. Vous pouvez définir des remplacements avec des dates relatives ou absolues. Tous les contrats provisionnés avec un package contiendront les remplacements définis.
  8. Examinez la grille tarifaire et cliquez sur Save pour créer la carte complétée.
Pour créer ce package en utilisant l’API, exécutez l’appel suivant : 
curl https://api.metronome.com/v1/packages/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
	  "name": "Starter Plan (as of Oct 2025)",
	  "rate_card_alias": "Tokens rate card",
	  "aliases": [{
	    "name": "Starter Plan",
		"starting_at": "2025-10-01T00:00:00.000Z"
	  }],
	  "net_payment_terms_days": 15,
	  "duration": {
		"value": 12,
		"unit": "MONTHS"
	  },
	  "recurring_credits": [{
	    "product_id": "5cd945a1-7a70-4875-b2b3-f9e3b28c647c",
		"access_amount": {
		  "unit_price": 1000,
		  "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2"
		},
		"priority": 1,
		"commit_duration": {
		  "value": 1,
		  "unit": "PERIODS"
		},
		"starting_at_offset": {
		  "value": 0,
		  "unit": "MONTHS"
		},
		"duration": {
		  "value": 3,
		  "unit": "MONTHS"
		}
	  }],
	  "subscriptions":[{
	    "collection_schedule": "advance",
        "initial_quantity": 1,
        "proration": {
          "invoice_behavior": "BILL_IMMEDIATELY",
          "is_prorated": true
        },
        "subscription_rate": {
          "billing_frequency": "monthly",
          "product_id": "76f29162-7f5c-4ee6-89ed-ebbd592d767e"
        },
	}]
  }'
INFOUtilisez starting_at_offset sur les conditions de package pour définir starting_at par rapport à la date de début du contrat et duration pour définir ending_before par rapport au starting_at_offset. Pour les conditions avec des dates ponctuelles sans durée, utilisez date_offset

​
Provisionner des clients avec un package

Provisionnez un client en utilisant le point de terminaison /contracts/create. Pour provisionner un client avec l’exemple de package Starter Plan, exécutez l’appel API suivant : 
curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "aa58107d-162f-407e-9f09-940f16adbb1c",
    "starting_at": "2025-10-01T00:00:00.000Z",
    "package_alias": "Starter Plan"
   }'
Le client est maintenant provisionné avec un contrat Starter Plan débutant le 1er octobre 2025, avec un abonnement mensuel de 10 pourladureˊeducontratetuncreˊditreˊcurrentde10pour la durée du contrat et un crédit récurrent de 10 qui se termine le 1er janvier 2026. Les contrats provisionnés avec un package ont un ID de package attaché visible dans l’application Metronome, l’export de données et l’API.
PACKAGES STANDARD UNIQUEMENTMetronome accepte actuellement uniquement package_id (ou package_alias) et transition lors du provisionnement d’un client avec un package. Passer toute condition supplémentaire à l’appel createContract retournera une erreur 400 lorsqu’utilisé en conjonction avec des packages.

​
Mettre à jour la tarification d’un package

Les packages ne peuvent actuellement pas être modifiés après leur création. Pour introduire une nouvelle version de package, créez un nouveau package et définissez le calendrier d’alias. Par exemple, Gnome AI décide de mettre à jour son packaging Starter Plan afin que les nouveaux clients ne reçoivent plus le crédit d’inscription de 10 $ à partir du 1er février 2026. Pour modéliser ce scénario dans Metronome, créez un nouveau package avec le même alias Starter Plan : 
curl https://api.metronome.com/v1/packages/create \  
  -H "Authorization: Bearer <TOKEN>" \  
  -H "Content-Type: application/json" \  
  -d '{ 
		"name": "Starter Plan - Feb 2025",
		"rate_card_alias": "Tokens rate card",
		"aliases": [{
		  "name": "Starter Plan",
		  "starting_at": "2026-02-01T00:00:00.000Z"
		}],
		"net_payment_terms_days": 15,
		"duration": {
		  "value": 12,
		  "unit": "MONTHS"
		},
		"subscriptions":[{
		  "collection_schedule": "advance",  
	      "initial_quantity": 1,  
	      "proration": {  
	        "invoice_behavior": "BILL_IMMEDIATELY",  
	        "is_prorated": true  
	      },  
	      "subscription_rate": {  
	        "billing_frequency": "monthly",  
	        "product_id": "76f29162-7f5c-4ee6-89ed-ebbd592d767e"  
	      }  
		}]
  	}'
Comme Gnome AI provisionne déjà des clients en utilisant l’alias Starter Plan, tous les nouveaux clients s’inscrivant après le 1er février 2026 à minuit UTC seront automatiquement provisionnés sur le nouveau package sans avoir besoin de modifier la logique existante.

​
Voir et gérer les packages

Pour voir les packages existants, allez dans Offering → Packages dans l’application Metronome ou appelez /packages/list dans l’API. Pour faciliter la gestion des cohortes, visualisez les clients associés à un package donné dans l’application Metronome ou appelez /packages/listContractsonPackage dans l’API.
LES PACKAGES NE PEUVENT PAS ÊTRE MODIFIÉSCréez un nouveau package et provisionnez un client avec le nouveau package ou modifiez le contrat sous-jacent en utilisant editContract.

​
Définir des champs personnalisés sur les conditions de package

Lors de la création d’un package, les utilisateurs peuvent définir des champs personnalisés sur les conditions du package. Les champs personnalisés sur les conditions de package seront transmis aux contrats associés. Les champs personnalisés de package ne peuvent pas être mis à jour après avoir été définis, mais les champs personnalisés définis par les packages au niveau du contrat peuvent être mis à jour en utilisant /customFields/setValues. Actuellement, Metronome prend en charge les champs personnalisés pour : package_commit, package_credit, package_scheduled_charge et package_subscription.