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 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

Read more about Contract Overrides.

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.

Read more about Credits and Commits.

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)

Read more about Subscriptions.

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.