List commits

curl --request POST \
  --url https://api.metronome.com/v1/contracts/customerCommits/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "commit_id": "6162d87b-e5db-4a33-b7f2-76ce6ead4e85",
  "include_ledgers": true
}
'

{
  "data": [
    {
      "id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
      "type": "PREPAID",
      "rate_type": "LIST_RATE",
      "name": "My test commit",
      "description": "My test commit description",
      "priority": 100,
      "product": {
        "id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
        "name": "My product A"
      },
      "rollover_fraction": 0.1,
      "applicable_product_ids": [
        "13a2179b-f0cb-460b-85a1-cd42964ca533"
      ],
      "applicable_contract_ids": [
        "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
      ],
      "access_schedule": {
        "credit_type": {
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
          "name": "USD (cents)"
        },
        "schedule_items": [
          {
            "id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a",
            "amount": 10000000,
            "starting_at": "2020-02-01T00:00:00.000Z",
            "ending_before": "2021-02-01T00:00:00.000Z"
          }
        ]
      },
      "invoice_schedule": {
        "credit_type": {
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
          "name": "USD (cents)"
        },
        "schedule_items": [
          {
            "id": "f15e4e23-f74e-4de4-9b3a-8b07434116c4",
            "invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
            "amount": 10000000,
            "unit_price": 10000000,
            "quantity": 1,
            "timestamp": "2020-03-01T00:00:00.000Z"
          }
        ],
        "do_not_invoice": false
      },
      "invoice_contract": {
        "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
      },
      "ledger": [
        {
          "invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
          "amount": 10000000,
          "timestamp": "2020-03-01T00:00:00.000Z",
          "type": "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION",
          "segment_id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a"
        }
      ],
      "uniqueness_key": "946g9bepi1-uniqueness-key",
      "created_at": "2020-01-01T00:00:00.000Z"
    }
  ],
  "next_page": null
}

Credits and commits

List commits

Retrieve all commit agreements for a customer, including both prepaid and postpaid commitments. This endpoint provides comprehensive visibility into contractual spending obligations, enabling you to track commitment utilization and manage customer contracts effectively.

Use this endpoint to:

Display commitment balances and utilization in customer dashboards
Track prepaid commitment drawdown and remaining balances
Monitor postpaid commitment progress toward minimum thresholds
Build commitment tracking and forecasting tools
Show commitment history with optional ledger details
Manage rollover balances between contract periods

Key response fields:

An array of Commit objects containing:

Commit type: PREPAID (pay upfront) or POSTPAID (pay at true-up)
Rate type: COMMIT_RATE (discounted) or LIST_RATE (standard pricing)
Access schedule: When commitment funds become available
Invoice schedule: When the customer is billed
Product targeting: Which product(s) usage is eligible to draw from this commit
Optional ledger entries: Transaction history (if include_ledgers=true)
Balance information: Current available amount (if include_balance=true)
Rollover settings: Fraction of unused amount that carries forward

Usage guidelines:

Pagination: Results limited to 25 commits per page; use ‘next_page’ for more
Date filtering options:
- covering_date: Commits active on a specific date
- starting_at: Commits with access on/after a date
- effective_before: Commits with access before a date (exclusive)
Scope options:
- include_contract_commits: Include contract-level commits (not just customer-level)
- include_archived: Include archived commits and commits from archived contracts
Performance considerations:
- include_ledgers: Adds detailed transaction history (slower)
- include_balance: Adds current balance calculation (slower)
Optional filtering: Use commit_id to retrieve a specific commit

POST

contracts

customerCommits

list

List commits

curl --request POST \
  --url https://api.metronome.com/v1/contracts/customerCommits/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "commit_id": "6162d87b-e5db-4a33-b7f2-76ce6ead4e85",
  "include_ledgers": true
}
'

{
  "data": [
    {
      "id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
      "type": "PREPAID",
      "rate_type": "LIST_RATE",
      "name": "My test commit",
      "description": "My test commit description",
      "priority": 100,
      "product": {
        "id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
        "name": "My product A"
      },
      "rollover_fraction": 0.1,
      "applicable_product_ids": [
        "13a2179b-f0cb-460b-85a1-cd42964ca533"
      ],
      "applicable_contract_ids": [
        "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
      ],
      "access_schedule": {
        "credit_type": {
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
          "name": "USD (cents)"
        },
        "schedule_items": [
          {
            "id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a",
            "amount": 10000000,
            "starting_at": "2020-02-01T00:00:00.000Z",
            "ending_before": "2021-02-01T00:00:00.000Z"
          }
        ]
      },
      "invoice_schedule": {
        "credit_type": {
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
          "name": "USD (cents)"
        },
        "schedule_items": [
          {
            "id": "f15e4e23-f74e-4de4-9b3a-8b07434116c4",
            "invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
            "amount": 10000000,
            "unit_price": 10000000,
            "quantity": 1,
            "timestamp": "2020-03-01T00:00:00.000Z"
          }
        ],
        "do_not_invoice": false
      },
      "invoice_contract": {
        "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
      },
      "ledger": [
        {
          "invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
          "amount": 10000000,
          "timestamp": "2020-03-01T00:00:00.000Z",
          "type": "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION",
          "segment_id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a"
        }
      ],
      "uniqueness_key": "946g9bepi1-uniqueness-key",
      "created_at": "2020-01-01T00:00:00.000Z"
    }
  ],
  "next_page": null
}

Authorizations

Authorization

string

header

required

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

Body

application/json

List all commits for a customer

customer_id

string<uuid>

required

commit_id

string<uuid>

covering_date

string<date-time>

Include only commits that have access schedules that "cover" the provided date

starting_at

string<date-time>

Include only commits that have any access on or after the provided date

effective_before

string<date-time>

Include only commits that have any access before the provided date (exclusive)

include_contract_commits

boolean

Include commits on the contract level.

include_archived

boolean

Include archived commits and commits from archived contracts.

include_ledgers

boolean

Include commit ledgers in the response. Setting this flag may cause the query to be slower.

include_balance

boolean

Include the balance in the response. Setting this flag may cause the query to be slower.

next_page

string

The next page token from a previous response.

limit

integer

default:25

The maximum number of commits to return. Defaults to 25.

Required range: 1 <= x <= 25

Response

200 - application/json

Success

data

object[]

required

Show child attributes

data.id

string<uuid>

required

data.type

enum<string>

required

Available options:

PREPAID,

POSTPAID

data.product

object

required

Show child attributes

data.product.id

string<uuid>

required

data.product.name

string

required

data.created_at

string<date-time>

required

Timestamp of when the commit was created.

Recurring commits: latter of commit service period date and parent commit start date
Rollover commits: when the new contract started

data.contract

object

Show child attributes

data.contract.id

string<uuid>

required

data.rate_type

enum<string>

Available options:

COMMIT_RATE,

LIST_RATE

data.name

string

data.priority

number

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

data.access_schedule

object

The schedule that the customer will gain access to the credits purposed with this commit.

Show child attributes

data.access_schedule.schedule_items

object[]

required

Show child attributes

data.access_schedule.schedule_items.id

string<uuid>

required

data.access_schedule.schedule_items.amount

number

required

data.access_schedule.schedule_items.starting_at

string<date-time>

required

data.access_schedule.schedule_items.ending_before

string<date-time>

required

data.access_schedule.credit_type

object

Show child attributes

data.access_schedule.credit_type.name

string

required

data.access_schedule.credit_type.id

string<uuid>

required

data.invoice_schedule

object

The schedule that the customer will be invoiced for this commit.

Show child attributes

data.invoice_schedule.credit_type

object

Show child attributes

data.invoice_schedule.credit_type.name

string

required

data.invoice_schedule.credit_type.id

string<uuid>

required

data.invoice_schedule.schedule_items

object[]

Show child attributes

data.invoice_schedule.schedule_items.id

string<uuid>

required

data.invoice_schedule.schedule_items.amount

number

required

data.invoice_schedule.schedule_items.unit_price

number

required

data.invoice_schedule.schedule_items.quantity

number

required

data.invoice_schedule.schedule_items.timestamp

string<date-time>

required

data.invoice_schedule.schedule_items.invoice_id

string<uuid> | null

data.invoice_schedule.do_not_invoice

boolean

default:false

This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.

data.invoice_contract

object

The contract that this commit will be billed on.

Show child attributes

data.invoice_contract.id

string<uuid>

required

data.rolled_over_from

object

Show child attributes

data.rolled_over_from.commit_id

string<uuid>

required

data.rolled_over_from.contract_id

string<uuid>

required

data.description

string

data.rollover_fraction

number

data.applicable_product_ids

string<uuid>[]

data.applicable_product_tags

string[]

data.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.

Show child attributes

data.specifiers.product_id

string<uuid>

If provided, the specifier will only apply to the product with the specified ID.

data.specifiers.product_tags

string[]

If provided, the specifier will only apply to products with all the specified tags.

data.specifiers.pricing_group_values

object

Show child attributes

data.specifiers.pricing_group_values.{key}

string

data.specifiers.presentation_group_values

object

Show child attributes

data.specifiers.presentation_group_values.{key}

string

data.applicable_contract_ids

string<uuid>[]

data.amount

number

(DEPRECATED) Use access_schedule + invoice_schedule instead.

data.ledger

object[]

A list of ordered events that impact the balance of a commit. For example, an invoice deduction or a rollover.

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8
Option 9
Option 10
Option 11
Option 12

Show child attributes

data.ledger.type

enum<string>

required

Available options:

PREPAID_COMMIT_SEGMENT_START

data.ledger.timestamp

string<date-time>

required

data.ledger.amount

number

required

data.ledger.segment_id

string<uuid>

required

data.balance

number

The current balance of the credit or commit. This balance reflects the amount of credit or commit that the customer has access to use at this moment - thus, expired and upcoming credit or commit segments contribute 0 to the balance. The balance will match the sum of all ledger entries with the exception of the case where the sum of negative manual ledger entries exceeds the positive amount remaining on the credit or commit - in that case, the balance will be 0. All manual ledger entries associated with active credit or commit segments are included in the balance, including future-dated manual ledger entries.

data.custom_fields

object

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

Show child attributes

data.custom_fields.{key}

string

data.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

data.archived_at

string<date-time>

RFC 3339 timestamp indicating when the commit was archived. If not provided, the commit is not archived.

next_page

string | null

required

Create a credit

List credits

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

List commits

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Body

Response