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

next_page

string | null

required

Create a credit

List credits

⌘I