Skip to main content
BETA FEATUREPackages are currently in beta and only accessible through the API. Contact your Metronome representative for access.
A package is a reusable, time-relative set of contract terms. Packages enable you to maintain only one rate card while supporting a variety of pricing plans to optimize for simplicity and flexibility. Define a package in Metronome to encode a standardized set of contract terms once and then provision many customers against that same package, making it easy to manage cohorts with identical contract structures. Use packages to model standard pay-as-you-go motions with Good/Better/Best plans (see the Pay as you go guide) to provision customers in a consistent and scalable way.

​
Prerequisites

Before creating a package, you must have:

​
Creating a Package

Create packages using the /packages/create endpoint. Package creation is nearly identical to contract creation, with the following exceptions:
  • Packages are customer agnostic. Do not pass a customer_id or a customer billing configuration when creating a package
  • Packages are time-relative. Set starting_at_offset and duration for relative length instead of starting_at and ending_before dates.
  • Packages support aliases [coming soon]. Similar to rate card aliases, packages support aliases that aid in programmatically managing new package rollouts.
Consider an example AI company with a Starter Plan that includes:
  • a $10 recurring sign-up credit applied to input and output tokens for the first 3 months
  • a $10 monthly subscription fee
  • Standard input and output token rates
To create this package using the API, execute the following call: 
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",
	  "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"
        },
		 }]
  }'
INFOUse starting_at_offset on package terms to define starting_at relative to contract start date and duration to define ending_before relative to the starting_at_offset. For terms with point-in-time dates without a duration, use date_offset

​
Provision customers with a package

Provision a customer using the /contracts/create endpoint. To provision a customer with the example Starter Plan package, execute the following API call: 
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_id": "dc25e803-2616-4c49-ba64-4988bc8173e7"
   }'
The customer is now provisioned with a Starter Plan contract beginning October 1, 2025, with a $10 monthly subscription for the contract duration and a $10 recurring credit that ends on Jan 1, 2026.
STANDARD PACKAGES ONLYProvision a customer with a package using package_id only. Passing in any additional terms to the createContract call will return a 400 error when used in conjunction with packages.
PACKAGES CANNOT BE EDITEDCreate a new package and provision a customer with the new package or edit the underlying contract using editContract.

​
What should I expect to see in future releases?

Future releases will enable:
  • UI improvements, including the ability to create and view packages directly in the Metronome app.
  • Cohort management in the UI and API: Easily pull a list of customers and contracts associated with a given package to make changes and understand spend across cohorts.
  • Package transitions in the UI and API: Add an alias to a package with an attached schedule to facilitate the introduction of new pricing plans. Use an alias in your customer provisioning workflows so that new customers are automatically provisioned to the package that the alias points to, without needing to update code.
  • Improved package creation in the UI and API: Add overrides with absolute dates to model certain discounted periods (e.g., all customers have 20% during the month of January, regardless of sign-up date). Set custom fields on package terms to connect downstream systems or enable more granular tagging of terms.