Assign contracts to customers
A contract is the most flexible way to provision a customer, and the easiest way to run your billing on Metronome. A contract determines a customer's products, pricing schedules, committed spending, and more. Active contracts can be edited (for example, to change pricing at a specified date). And updates to an underlying rate card—for example, to launch new products—bubble up to all customers contracted to the rate card.
Contracts represent a variable combination of products and adjustments, including:
- Rate card
- Rate card overrides
- Commits (prepaid or postpaid)
- Credits
- Fixed products (one-time or recurring)
Learn how to create an unmodified contract, and then explore ways to configure them.
Create contracts
Once you've set up at least one rate card or fixed product, you can create a contract for an existing customer. Note that you must create the customer before following these steps.
At a minimum, a contract combines a customer, rate card or fixed product, and a starting at date.
To create a contract in the Metronome app:
- On the Customers page, click on the customer record.
- On the customer's detail page, click New contract or plan -> New contract.
- On the resulting contract configuration page
- Enter an optional contract name.
- Select the applicable rate card.
- Enter the starting date, and optional ending date.
- Click Save.
Add commits
Commits represent spending agreements made as part of a contract. For example, a contract may require a customer to pay a certain amount at the start of a contract (a prepaid commit) or at the end (postpaid). Commits aid in accurate reporting of a customer's spend and your revenue.
Prepaid commits, the most common type, have two components:
- An access schedule sets the commitment amount and duration
- An invoice schedule sets how much the customer pays and how frequently
Postpaid commits require a true-up invoice. For example, if a customer committed to spending $10,000 over the contract's duration but was only actually billed $9,500 during that time, Metronome automatically calculates and creates an invoice at the contract end for the other $500. If the customer spent more than $10,000, no additional invoice is necessary.
To add a commit to a contract:
-
Define a fixed product to represent the commit (for example, named Prepaid commitment or Postpaid commitment).
-
On the Configure your contract page, click Add commit.
-
Select the appropriate product created in Step 1.
-
Optionally add applicable products or tags if the commitment only applies to some products.
-
Select and configure the commit type: prepaid or postpaid.
Postpaid commits only require the commitment amount. Prepaid commits are highly configurable.
-
Click Add.
Commitments and fixed products can have distinct invoicing schedules from invoices for usage-based products.
Add credits
Metronome supports the ability to adjust a customer's balance by issuing credits. Credits can be associated with a contract and used to model promotions, reimbursement for downtime, and more. Similar to commits, credits:
- Have an access schedule (with multiple segments)
- Can apply to specific products or product tags
- Have a required priority assignment
Learn more about using commits and credits.
Override rate cards
Rate cards define default pricing and availability (entitlement) of products. Both can be overridden when a contract is created. You can use rate card overrides to:
- Lock prices for active products on the contract by setting overrides on them when the contract starts
- Apply list price reductions to downstream contracts
- Set Multiplier adjustments on product tags to create a discount of say 20% on any new product that is launched with that tag in the future
To override a rate card when creating a contract, under Rates, click Add an override. In the resulting modal:
- Search for and select the product.
- Optionally change the ending before date if you want the override to be temporary.
- Optionally change the entitlement to make a non-public product available to this customer.
- To override the rate, change the Adjustment type to Multiplier or Overwrite. Multiplier reduces or increases the rate by a set percentage. Overwrite sets a new rate, which can use flat or tiered pricing.
- Click Create.
Prioritize Multiplier overrides
Metronome supports more exact control on the impact of overrides by prioritizing Multiplier adjustments. Configure Multiplier override behavior by setting a prioritization scheme on the contract. There are two options:
-
Lowest Multiplier (default)
By default, Metronome applies multiplier overrides in order from largest discount to smallest.
-
Explicit
Alternatively, choose explicit prioritization and give each override a priority as a number greater than 0. Explicit priorities are applied from lowest number to highest.
Note that Overwrite overrides always take priority over Multiplier overrides.
As a real-world example of using prioritization, say a product has the tags "Beta" and "Global" and you create an override for each:
- 0.9 multiplier override on product tag "Beta"
- 0.7 multiplier override on product tag "Global"
If the prioritization scheme is Lowest Multiplier (the default), then the 0.7 override applies. If the prioritization scheme is Explicit, you set which override applies.
Use rate card aliases
You can optionally create an alias for a rate card when you create it, and then use the alias—not the rate card ID—when assigning a contract to a customer. Rate card aliases can be changed on a schedule, making them reusable.
For example, say you create new contracts using the alias "north-america-pricing", which points to rate card NA-1. You can later change the alias of rate card NA-1 to "north-america-deprecated" and then simultaneously assign the same alias "north-america-pricing" to another rate card, NA-2. Your existing code for creating new contracts automatically resolve to point to the correct rate card for the alias.
Alias assignment uses starting_at and ending_before parameters to handle when an alias becomes active or inactive. Here’s a simple example for switching users from rate card NA-1 to NA-2 starting on January 1, 2025:
- Add the alias north-america-pricing-deprecated to NA-1, with starting_at = 2025-01-01
- Assign the alias north-america-pricing to NA-2, also with starting_at = 2025-01-01
NA-1 now has two aliases:
- north-america-pricing (no end date)
- north-america-pricing-deprecated (starts on 2025-01-01)
NA-2 has the alias north-america-pricing, which starts on 2025-01-01.
This means before January 1, 2025, NA-1 still uses the north-america-pricing alias. Starting on January 1, 2025, the north-america-pricing alias moves to NA-2, while NA-1 retains the north-america-pricing-deprecated alias.
When using scheduled aliases, keep in mind:
- A rate card can have more than one alias at the same time, with timing determining when each alias is active.
- When an alias is assigned to a new rate card, it stops pointing to the old one after the starting_at date on the new card.
- Changing an alias doesn’t impact existing contracts. New contracts created after the alias switch use the new rate card, while contracts signed before the change still point to the original card.
Add additional terms
Additional terms is where you add fixed products to a contract. These can represent one-time charges, like a setup fee, or recurring ones. Fixed products are never usage-based.
To add an additional term when creating a contract, under Additional terms, click Add a term -> Scheduled charge. In the resulting modal:
- Search for and select the product.
- Select the billing frequency (one-time, monthly, and so on).
- Select a date for the first (or only) invoice.
- Enter the quantity of the product to charge for, and the unit price.
- Click Create.
As explained in how invoicing works for contracts, fixed products are invoiced on a separate schedule from usage-based and composite products.
Configure billing
Two billing properties can be set on the contract level: net payment terms (default of 30 days) and the application of a usage filter.
A usage filter is helpful when a customer has multiple active contracts. Usage-based and composite products bill based upon usage events sent to Metronome. By default all events for a customer apply to all contracts for that customer (assuming all contracts include a product using that event).
Application of a usage filter calculates the billing for a subset of events on a specific contract. For example, if you bill a customer for usage but invoice different regions on separate contracts, apply a usage filter to simplify reporting without needing to send different billable metrics. To do so, create a group key when designing the billable metric, then filter by the same group key on the contract.
Update contracts
You can update the end date of a contract at any time.
Additionally, you can amend a contract to push new terms. Amendments can implement upsells or customer renegotiations. An amendment can be scheduled to add new commits, overrides, scheduled charges, and discounts. You cannot use amendments to remove existing terms.
The lifecycle tab on a customer's contract displays a chronological history of the contract.