Create a contract

curl --request POST \
  --url https://api.metronome.com/v1/contracts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "starting_at": "2020-01-01T00:00:00.000Z",
  "billing_provider_configuration": {
    "billing_provider": "stripe",
    "delivery_method": "direct_to_billing_provider"
  }
}
'

{
  "data": {
    "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "contract": {
      "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "commits": [],
      "credits": [],
      "overrides": [],
      "scheduled_charges": [],
      "transitions": [],
      "subscriptions": [],
      "recurring_commits": [],
      "recurring_credits": [],
      "created_at": "2020-01-01T00:00:00.000Z",
      "created_by": "system",
      "usage_statement_schedule": {
        "frequency": "MONTHLY",
        "billing_anchor_date": "2020-01-01T00:00:00.000Z"
      },
      "usage_filter": []
    }
  }
}

Contracts

Create a contract

Contracts define a customer’s products, pricing, discounts, access duration, and billing configuration. Contracts serve as the central billing agreement for both PLG and Enterprise customers. You can automatically grant customers access to your products and services directly from your product or CRM.

Use this endpoint to:

PLG onboarding: Automatically provision new self-serve customers with contracts when they sign up.
Enterprise sales: Push negotiated contracts from Salesforce with custom pricing and commitments
Promotional pricing: Implement time-limited discounts and free trials through overrides

Key components:

Contract Term and Billing Schedule

Set contract duration using starting_at and ending_before fields. PLG contracts typically use perpetual agreements (no end date), while Enterprise contracts have fixed end dates which can be edited over time in the case of co-term upsells.

Rate Card

If you are offering usage based pricing, you can set a rate card for the contract to reference through rate_card_id or rate_card_alias. The rate card is a store of all of your usage based products and their centralized pricing. Any new products or price changes on the rate card can be set to automatically propagate to all associated contracts - this ensures consistent pricing and product launches flow to contracts without manual updates and migrations. The usage_statement_schedule determines the cadence on which Metronome will finalize a usage invoice for the customer. This defaults to monthly on the 1st, with options for custom dates, quarterly, or annual cadences. Note: Most usage based billing companies align usage statements to be evaluated aligned to the first of the month. Read more about Rate Cards.

Overrides and discounts

Customize pricing on the contract through time-bounded overrides that can target specific products, product families, or complex usage scenarios. Overrides enable two key capabilities:

Discounts: Apply percentage discounts, fixed rate reductions, or quantity-based pricing tiers
Entitlements: Provide special pricing or access to specific products for negotiated deals

Commits and Credits

Using commits, configure prepaid or postpaid spending commitments where customers promise to spend a certain amount over the contract period paid in advance or in arrears. Use credits to provide free spending allowances. Under the hood these are the same mechanisms, however, credits are typically offered for free (SLA or promotional) or as a part of an allotment associated with a Subscription.

In Metronome, you can set commits and credits to only be applicable for a subset of usage. Use applicable_product_ids or applicable_product_tags to create product or product-family specific commits or credits, or you can build complex boolean logic specifiers to target usage based on pricing and presentation group values using override_specifiers.

These objects can also also be configured to have a recurrence schedule to easily model customer packaging which includes recurring monthly or quarterly allotments.

Commits support rollover settings (rollover_fraction) to transfer unused balances between contract periods, either entirely or as a percentage.

Subscriptions

You can add a fixed recurring charge to a contract, like monthly licenses or seat-based fees, using the subscription charge. Subscription charges are defined on your rate card and you can select which subscription is applicable to add to each contract. When you add a subscription to a contract you need to:

Define whether the subscription is paid for in-advance or in-arrears (collection_schedule)
Define the proration behavior (proration)
Specify an initial quantity (initial_quantity)
Define which subscription rate on the rate card should be used (subscription_rate)

Scheduled Charges

Set up one-time, recurring, or entirely custom charges that occur on specific dates, separate from usage-based billing or commitments. These can be used to model non-recurring platform charges or professional services.

Threshold Billing

Metronome allows you to configure automatic billing triggers when customers reach spending thresholds to prevent fraud and manage risk. You can use spend_threshold_configuration to trigger an invoice to cover current charges whenever the threshold is reached or you can ensure the customer maintains a minimum prepaid balance using the prepaid_balance_configuration.

Read more about Spend Threshold and Prepaid Balance Thresholds.

Usage guidelines:

You can always Edit Contracts after it has been created, using the editContract endpoint. Metronome keeps track of all edits, both in the audit log and over the getEditHistory endpoint.
Customers in Metronome can have multiple concurrent contracts at one time. Use usage_filters to route the correct usage to each contract. Read more about usage filters.

POST

contracts

create

Create a contract

curl --request POST \
  --url https://api.metronome.com/v1/contracts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "starting_at": "2020-01-01T00:00:00.000Z",
  "billing_provider_configuration": {
    "billing_provider": "stripe",
    "delivery_method": "direct_to_billing_provider"
  }
}
'

{
  "data": {
    "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "contract": {
      "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "commits": [],
      "credits": [],
      "overrides": [],
      "scheduled_charges": [],
      "transitions": [],
      "subscriptions": [],
      "recurring_commits": [],
      "recurring_credits": [],
      "created_at": "2020-01-01T00:00:00.000Z",
      "created_by": "system",
      "usage_statement_schedule": {
        "frequency": "MONTHLY",
        "billing_anchor_date": "2020-01-01T00:00:00.000Z"
      },
      "usage_filter": []
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a new contract

customer_id

string<uuid>

required

starting_at

string<date-time>

required

inclusive contract start time

package_id

string<uuid>

If provided, provisions a customer on a package instead of creating a traditional contract. When specified, only customer_id, starting_at, package_id, uniqueness_key, transition, and custom_fields are allowed.

package_alias

string

Selects the package linked to the specified alias as of the contract's start date. Mutually exclusive with package_id.

name

string

uniqueness_key

string

Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.

Required string length: 1 - 128

net_payment_terms_days

number

rate_card_id

string<uuid>

rate_card_alias

string

Selects the rate card linked to the specified alias as of the contract's start date.

ending_before

string<date-time>

exclusive contract end time

commits

object[]

Show child attributes

credits

object[]

Show child attributes

recurring_commits

object[]

Show child attributes

recurring_credits

object[]

Show child attributes

multiplier_override_prioritization

enum<string>

Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first. If tiered overrides are used, prioritization must be explicit.

Available options:

LOWEST_MULTIPLIER,

lowest_multiplier,

EXPLICIT,

explicit

overrides

object[]

Show child attributes

scheduled_charges

object[]

Show child attributes

scheduled_charges_on_usage_invoices

enum<string>

Determines which scheduled and commit charges to consolidate onto the Contract's usage invoice. The charge's timestamp must match the usage invoice's ending_before date for consolidation to occur. This field cannot be modified after a Contract has been created. If this field is omitted, charges will appear on a separate invoice from usage charges.

Available options:

ALL

transition

object

Show child attributes

usage_filter

object

Show child attributes

usage_statement_schedule

object

Show child attributes

custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

billing_provider_configuration

object

The billing provider configuration associated with a contract. Provide either an ID or the provider and delivery method.

Show child attributes

spend_threshold_configuration

object

Show child attributes

prepaid_balance_threshold_configuration

object

Show child attributes

subscriptions

object[]

Optional list of subscriptions to add to the contract.

Show child attributes

hierarchy_configuration

object

Show child attributes

Response

Success

data

object

required

Show child attributes

Archive a billable metric

Get a contract (v2)

⌘I