Create a commit
⚠️ For most contract amendments, use contracts/edit directly. Use this endpoint only for cross-contract or enterprise-wide commits.
Creates customer-level commits that establish spending commitments for customers across their Metronome usage. Commits represent contracted spending obligations that can be either prepaid (paid upfront) or postpaid (billed later).
Note: In most cases, you should add commitments directly to customer contracts using the contract/create or contract/edit APIs.
Use this endpoint to:
Use this endpoint when you need to establish customer-level spending commitments that can be applied across multiple contracts or scoped to specific contracts. Customer-level commits are ideal for:
- Enterprise-wide minimum spending agreements that span multiple contracts
- Multi-contract volume commitments with shared spending pools
- Cross-contract discount tiers based on aggregate usage
Commit type Requirements:
- You must specify either “prepaid” or “postpaid” as the commit type:
- Prepaid commits: Customer pays upfront; invoice_schedule is optional (if omitted, creates a commit without an invoice)
- Postpaid commits: Customer pays when the commitment expires (the end of the access_schedule); invoice_schedule is required and must match access_schedule totals.
Billing configuration:
- invoice_contract_id is required for postpaid commits and for prepaid commits with billing (only optional for free prepaid commits) unless do_not_invoice is set to true
- For postpaid commits: access_schedule and invoice_schedule must have matching amounts
- For postpaid commits: only one schedule item is allowed in both schedules.
Scoping flexibility:
Customer-level commits can be configured in a few ways:
- Contract-specific: Use the
applicable_contract_idsfield to limit the commit to specific contracts - Cross-contract: Leave
applicable_contract_idsempty to allow the commit to be used across all of the customer’s contracts
Product targeting:
Commits can be scoped to specific products using applicable_product_ids, applicable_product_tags, or specifiers, or left unrestricted to apply to all products.
Priority considerations:
When multiple commits are applicable, the one with the lower priority value will be consumed first. If there is a tie, contract level commits and credits will be applied before customer level commits and credits. Plan your priority scheme carefully to ensure commits are applied in the desired order.
Usage guidelines:
⚠️ Preferred Alternative: In most cases, you should add commits directly to contracts using the create contract or edit contract APIs instead of creating customer-level commits. Contract-level commits provide better organization and are the recommended approach for standard use cases.
Authorizations
Body
Create a commit
List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags.