Create a commit

curl --request POST \
  --url https://api.metronome.com/v1/contracts/customerCommits/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "type": "prepaid",
  "name": "My Commit",
  "priority": 100,
  "product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
  "invoice_contract_id": "e57d6929-c2f1-4796-a9a8-63cedefe848d",
  "access_schedule": {
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "schedule_items": [
      {
        "amount": 1000,
        "starting_at": "2020-01-01T00:00:00.000Z",
        "ending_before": "2020-02-01T00:00:00.000Z"
      }
    ]
  },
  "invoice_schedule": {
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "schedule_items": [
      {
        "unit_price": 10000000,
        "quantity": 1,
        "timestamp": "2020-03-01T00:00:00.000Z"
      }
    ],
    "do_not_invoice": false
  }
}
'

{
  "data": {
    "id": "6162d87b-e5db-4a33-b7f2-76ce6ead4e85"
  }
}

Credits and commits

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) 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_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.

POST

contracts

customerCommits

create

Create a commit

curl --request POST \
  --url https://api.metronome.com/v1/contracts/customerCommits/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "type": "prepaid",
  "name": "My Commit",
  "priority": 100,
  "product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
  "invoice_contract_id": "e57d6929-c2f1-4796-a9a8-63cedefe848d",
  "access_schedule": {
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "schedule_items": [
      {
        "amount": 1000,
        "starting_at": "2020-01-01T00:00:00.000Z",
        "ending_before": "2020-02-01T00:00:00.000Z"
      }
    ]
  },
  "invoice_schedule": {
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "schedule_items": [
      {
        "unit_price": 10000000,
        "quantity": 1,
        "timestamp": "2020-03-01T00:00:00.000Z"
      }
    ],
    "do_not_invoice": false
  }
}
'

{
  "data": {
    "id": "6162d87b-e5db-4a33-b7f2-76ce6ead4e85"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a commit

customer_id

string<uuid>

required

type

enum<string>

required

Available options:

PREPAID,

prepaid,

POSTPAID,

postpaid

priority

number

required

If multiple credits or commits are applicable, the one with the lower priority will apply first.

product_id

string<uuid>

required

ID of the fixed product associated with the commit. This is required because products are used to invoice the commit amount.

access_schedule

object

required

Schedule for distributing the commit to the customer. For "POSTPAID" commits only one schedule item is allowed and amount must match invoice_schedule total.

Show child attributes

rate_type

enum<string>

Available options:

COMMIT_RATE,

commit_rate,

LIST_RATE,

list_rate

name

string

displayed on invoices

Minimum string length: 1

description

string

Used only in UI/API. It is not exposed to end customers.

invoice_schedule

object

Required for "POSTPAID" commits: the true up invoice will be generated at this time and only one schedule item is allowed; the total must match accesss_schedule amount. Optional for "PREPAID" commits: if not provided, this will be a "complimentary" commit with no invoice.

Show child attributes

invoice_contract_id

string<uuid>

The contract that this commit will be billed on. This is required for "POSTPAID" commits and for "PREPAID" commits unless there is no invoice schedule above (i.e., the commit is 'free'), or if do_not_invoice is set to true.

applicable_product_ids

string<uuid>[]

Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.

applicable_product_tags

string[]

Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.

applicable_contract_ids

string[]

Which contract the commit applies to. If not provided, the commit applies to all contracts.

specifiers

object[]

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.

Show child attributes

custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

uniqueness_key

string

Prevents the creation of duplicates. If a request to create a commit or credit is made with a uniqueness key that was previously used to create a commit or credit, a new record will not be created and the request will fail with a 409 error.

Required string length: 1 - 128

Response

Success

data

object

required

Show child attributes

Archive a contract

Create a credit

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

Create a commit

Use this endpoint to:

Commit type Requirements:

Billing configuration:

Scoping flexibility:

Product targeting:

Priority considerations:

Usage guidelines:

Authorizations

Body

Response