Apply credits and commits to contracts
You can grant free credits and encode prepaid and postpaid commits on Metronome contracts. The balance of these credits and commits, and their application against draft invoices, updates continuously in real time as customers use your product. Credits and commits power a range of business models, from product-led growth motions to complex enterprise contracts.
How credits and commits work
Credits and commits in Metronome are flexible on these dimensions:
- Effective time period: Credits and commits have an
access_schedulethat defines spend allotments associated with one or many date ranges. Define the date ranges by any hour-aligned time, and only usage falling within the range consumes the credit or commit. - Applicable products: Specify a subset of products, defined by product IDs (
applicable_product_ids) or product tags (applicable_product_tags), to consume a credit or commit. Applicable product tags ensure that new products launched in an existing family can consume the correct commits automatically. - Invoice schedule: With prepaid commits, define a one-time invoice or break the payment into multiple invoices on any schedule. Customize the amount invoiced for any prepaid commit.
- Custom fields: Tag credits and commits with metadata useful for downstream workflows like alerting, data reconciliation, and revenue recognition. For example, get alerted when the remaining balance of credits with the custom field
free_trialreaches 0.
Grant a free credit
Credits give customers a dollar amount of free usage. Common scenarios for free credits include free trials, reimbursement for downtime (SLA credits), and promotions.
As a common scenario, clients grant free credits to a customer where the customer can use the credits during the access period for all active contracts. Learn how to provision customers with contracts.
To grant credits to a customer through the Metronome app:
- Go to Customers > select the customer > Contract commits and credits > click Add credit.
- Link the credit to a fixed product by selecting the Credit product from the dropdown. Credits and commits in Metronome are always associated with a fixed product. For example, you can create separate products for a free credit, SLA credit, and promotion credit.
- (Optional) Add an internal description to explain why you’re granting the credit.
- (Optional) If the credit can only be consumed by a subset of usage, specify applicable product IDs or applicable product tags. If omitted, all usage, subscription, and composite charges can consume credits.
- (Optional) If the credit should only be consumed by a subset of the customer’s contracts, specify applicable contract names or IDs. If omitted, usage tied to all contracts consumes the credit.
- Create an access schedule. An access schedule consists of one or more segments, each defined by a date range and associated with an amount. For example, to grant a $10/month credit for three months, create three segments in the access schedule:
- Define the priority of the credit. If a customer has multiple credits or commits that could apply against usage, the priority dictates the order in which the credits and commits are consumed. Lower priorities get consumed first. For example, you may want all credits to be consumed fist before consuming any commits. Read about the full list of prioritization rules.
This example API request shows how to create a free credit:
curl https://api.metronome.com/v1/contracts/customerCredits/create \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"name": "SLA Credit",
"priority": 1,
"product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
"access_schedule": {
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"schedule_items": [
{
"amount": 1000,
"starting_at": "2024-10-01T00:00:00.000Z",
"ending_before": "2024-11-01T00:00:00.000Z"
},
{
"amount": 1000,
"starting_at": "2024-11-01T00:00:00.000Z",
"ending_before": "2024-12-01T00:00:00.000Z"
},
{
"amount": 1000,
"starting_at": "2024-12-01T00:00:00.000Z",
"ending_before": "2025-01-01T00:00:00.000Z"
}
]
}
}'
Issue a prepaid or postpaid commit
Prepaid and postpaid commits represent an agreement by a customer to spend a dollar amount over a period of time. Prepaid commits get paid in advance, while postpaid commits get paid in arrears.
While usually associated with contracts, you can also encode commits at a customer level, where they’re consumed by all or a subset of contracts for that customer.
Prepaid commits
Prepaid commits get paid in advance.
For example, imagine a customer committed to $10,000 of spend over the lifetime of their contract, for which they get charged in two invoices: one for $4,000 and one for $6,000. The contract spans from October 01, 2024 to October 01, 2025.
To add a prepaid commit to a contract in the Metronome app:
- When creating a contract, click Add commit.
- Link the commit to a fixed product.
- (Optional) Add an internal description explaining the reason for granting the commit.
- (Optional) If the commit can only get consumed by a subset of usage, specify applicable product IDs or applicable product tags. If omitted, all usage, subscription, and composite charges can consume the commit.
- Create an access schedule. An access schedule consists of segments, each defined by a date range and associated with an amount. For example, set the access schedule to October 01, 2024 to October 01, 2025, matching the term of the contract.
- (Optional) Create an invoice schedule. This determines the cadence to bill your customer for the commit. You can bill your customer for any amount in any number of installments. For example, create two invoice schedule segments:
- One segment on October 01, 2024 for $4,000
- Another segment on November 01, 2024 for $6,000
- Define the priority of the commit. If a customer has multiple credits or commits that could apply against usage, the priority dictates the order in which the credits and commits are consumed. Lower priority commits get consumed first.
- (Optional) Specify the rollover percentage of the commit. In the case of a contract renewal, specify what percent of the initial balance of the commit should roll over to the new contract. Learn more about contract transitions.
This example API call shows how to create a contract with the example prepaid commit:
curl https://api.metronome.com/v1/contracts/create \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"starting_at": "2024-10-01T00:00:00.000Z",
"commits": [
{
"type": "prepaid",
"product_id": "cc69a00a-fa8f-4ae6-afdb-703e63fb4777",
"access_schedule": {
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"schedule_items": [
{
"amount": 100000,
"starting_at": "2024-10-01T00:00:00.000Z",
"ending_before": "2025-10-01T00:00:00.000Z"
}
]
},
"invoice_schedule": {
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"schedule_items": [
{
"amount": 400000,
"timestamp": "2024-10-01T00:00:00.000Z"
},
{
"amount": 600000,
"unit_price": 600000,
"quantity": 1,
"timestamp": "2024-11-01T00:00:00.000Z"
}
]
}
}
]
}'
Postpaid commits
For postpaid commits, usage during the access period (defined by access_schedule) gets paid for in arrears. If the total amount paid during the access period is less than the committed amount, there’s a final true-up invoice on the invoice_date.
For example, if a customer has a contract with a postpaid commitment to spend $10,000 over the one-year contract term from October 01, 2024 to October 01, 2025, billed monthly, each month, the customer gets billed in arrears for usage incurred in that month. At the end of the contract, the customer spent a total of $9,000. On the specified invoice_date, a true-up invoice for $1,000 is issued to reach the commitment of $10,000.
To add a postpaid commit to a contract in the Metronome app:
- When creating a contract, click Add commit.
- Link the commit to a fixed product.
- (Optional) Add an internal description explaining the reason for granting the commit.
- (Optional) If the commit can only get consumed by a subset of usage, specify applicable product IDs or applicable product tags. If omitted, all usage, subscription, and composite charges can consume the commit.
- Create an access schedule. By default, the access schedule is the term of the contract. You can allocate a proportion of spend to distinct time windows across the contract. In the example scenario, the access schedule is from October 01, 2024 to October 01, 2025.
- Select the invoice date. The invoice date is the date when a true-up invoice gets issued if the actual spend falls short of the committed amount. By default, the invoice date is the end date of the contract, but you can customize it to any date after the access schedule. For the example scenario, the invoice date is October 01, 2025, the end date of the contract.
- Define the priority of the commit. If a customer has multiple credits or commits that could apply against usage, the priority dictates the order in which the credits and commits are consumed. Lower priority commits get consumed first.
- (Optional) Specify the rollover percentage of the commit. In the case of a contract renewal, specify what percent of the initial balance of the commit should roll over to the new contract. Learn more about contract transitions.
This example API call shows how to create a contract with the example postpaid commit:
curl https://api.metronome.com/v1/contracts/create \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"starting_at": "2024-10-01T00:00:00.000Z",
"ending_before": "2025-10-01T00:00:00.000Z",
"commits": [
{
"type": "postpaid",
"product_id": "1cca616f-d6c7-44d3-b02d-cfcc85f97fd6",
"access_schedule": {
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"schedule_items": [
{
"amount": 1000000,
"starting_at": "2024-10-01T00:00:00.000Z",
"ending_before": "2025-10-01T00:00:00.000Z"
}
]
},
"invoice_schedule": {
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"schedule_items": [
{
"amount": 1000000,
"timestamp": "2025-10-01T00:00:00.000Z"
}
]
}
}
]
}'
How credits and commits work with invoices
In Metronome, credits and commits are always applied against usage at a line-item level rather than the aggregate invoice level. This attribution creates the ability to more accurately recognize precommitted and overage spend against each product.
On an invoice, line items are separated based on whether the usage draws down a commit, a credit, or is in overage.
The same usage can apply against only one commit or credit. For example, if you incurred $500 of usage and have a contract encoded with a $400 prepaid commit and a $400 postpaid commit, the prepaid commit gets consumed first. $400 of the usage fully consumes the prepaid commit. Then, the remaining $100 counts toward fulfilling the postpaid commit. As postpaid commits get paid in arrears, the customer would still get charged $100.
This example invoice API response demonstrates a situation where a customer consumed $10 of Data Storage during the billing period. Of the $10, $4 is covered by a prepaid commit, and $6 is not covered by a credit or commit. In the invoice response, this results in 3 line items:
- Usage covered by the prepaid commit, with a total of $4
- Commit application line item, with a total of -$4
- Usage not covered by a prepaid commit or credit (”Overage” line item), with a total of $6
{
"data" : {
"billable_status" : "billable",
"contract_custom_fields" : {},
"contract_id" : "222fd78f-c93d-4b11-bec8-a7b12b510214",
"credit_type" : {
"id" : "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name" : "USD (cents)"
},
"custom_fields" : {},
"customer_custom_fields" : {},
"customer_id" : "b61bf255-d6f2-49fc-a062-b32431e2d22d",
"end_timestamp" : "2024-11-01T00:00:00+00:00",
"external_invoice" : null,
"id" : "e1937b93-64a5-5117-99e1-eb963a71e764",
"issued_at" : "2024-11-02T12:00:00+00:00",
"line_items" : [
{
"commit_custom_fields" : {},
"commit_id" : "fde728f0-af26-45c3-92f6-7587dedadef3",
"commit_segment_id" : "fc696ca9-58b6-49e1-b2dc-888d78acd00e",
"commit_type" : "PrepaidCommit",
"credit_type" : {
"id" : "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name" : "USD (cents)"
},
"ending_before" : "2024-11-01T00:00:00+00:00",
"name" : "Data Storage",
"product_custom_fields" : {},
"product_id" : "c8dccd54-0ca8-4580-861d-1e26854ab2f1",
"product_type" : "UsageProductListItem",
"quantity" : 4,
"starting_at" : "2024-10-01T00:00:00+00:00",
"total" : 400,
"unit_price" : 100
},
{
"commit_custom_fields" : {},
"commit_id" : "fde728f0-af26-45c3-92f6-7587dedadef3",
"commit_netsuite_item_id" : "1234",
"commit_segment_id" : "fc696ca9-58b6-49e1-b2dc-888d78acd00e",
"commit_type" : "PrepaidCommit",
"credit_type" : {
"id" : "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name" : "USD (cents)"
},
"ending_before" : "2024-11-01T00:00:00+00:00",
"name" : "Prepaid Commit applied",
"product_custom_fields" : {},
"product_id" : "c8dccd54-0ca8-4580-861d-1e26854ab2f1",
"product_type" : "UsageProductListItem",
"starting_at" : "2024-10-01T00:00:00+00:00",
"total" : -400
},
{
"credit_type" : {
"id" : "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name" : "USD (cents)"
},
"ending_before" : "2024-11-01T00:00:00+00:00",
"name" : "Data Storage",
"product_custom_fields" : {},
"product_id" : "c8dccd54-0ca8-4580-861d-1e26854ab2f1",
"product_type" : "UsageProductListItem",
"quantity" : 6,
"starting_at" : "2024-10-01T00:00:00+00:00",
"total" : 600,
"unit_price" : 100
}
],
"start_timestamp" : "2024-10-01T00:00:00+00:00",
"status" : "DRAFT",
"total" : 600,
"type" : "USAGE"
}
}