Create a commit

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)
• 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_ids field to limit the commit to specific contracts
• Cross-contract: Leave applicable_contract_ids empty 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.