List credits

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

{
  "data": [
    {
      "id": "fa411f5b-fb85-4755-9d4d-530717be083c",
      "type": "CREDIT",
      "rate_type": "LIST_RATE",
      "name": "My test credit",
      "description": "My test credit description",
      "priority": 100,
      "product": {
        "id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
        "name": "My product A"
      },
      "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"
          }
        ]
      },
      "ledger": [
        {
          "invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
          "amount": 10000000,
          "timestamp": "2020-03-01T00:00:00.000Z",
          "type": "CREDIT_AUTOMATED_INVOICE_DEDUCTION",
          "segment_id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a"
        }
      ],
      "uniqueness_key": "372p7cvwr3-uniqueness-key"
    }
  ],
  "next_page": null
}

Credits and commits

List credits

Retrieve a detailed list of all credits available to a customer, including promotional credits and contract-specific credits. This endpoint provides comprehensive visibility into credit balances, access schedules, and usage rules, enabling you to build credit management interfaces and track available funding.

Use this endpoint to:

Display all available credits in customer billing dashboards
Show credit balances and expiration dates
Track credit usage history with optional ledger details
Build credit management and reporting tools
Monitor promotional credit utilization • Support customer inquiries about available credits

Key response fields:

An array of Credit objects containing:

Credit details: Name, priority, and which applicable products/tags it applies to
Product ID: The product_id of the credit. This is for external mapping into your quote-to-cash stack, not the product it applies to.
Access schedule: When credits become available and expire
Optional ledger entries: Transaction history (if include_ledgers=true)
Balance information: Current available amount (if include_balance=true)
Metadata: Custom fields and usage specifiers

Usage guidelines:

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

POST

contracts

customerCredits

list

List credits

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

{
  "data": [
    {
      "id": "fa411f5b-fb85-4755-9d4d-530717be083c",
      "type": "CREDIT",
      "rate_type": "LIST_RATE",
      "name": "My test credit",
      "description": "My test credit description",
      "priority": 100,
      "product": {
        "id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
        "name": "My product A"
      },
      "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"
          }
        ]
      },
      "ledger": [
        {
          "invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
          "amount": 10000000,
          "timestamp": "2020-03-01T00:00:00.000Z",
          "type": "CREDIT_AUTOMATED_INVOICE_DEDUCTION",
          "segment_id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a"
        }
      ],
      "uniqueness_key": "372p7cvwr3-uniqueness-key"
    }
  ],
  "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 credits for a customer

customer_id

string<uuid>

required

credit_id

string<uuid>

covering_date

string<date-time>

Return only credits that have access schedules that "cover" the provided date

starting_at

string<date-time>

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

effective_before

string<date-time>

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

include_contract_credits

boolean

Include credits on the contract level.

include_archived

boolean

Include archived credits and credits from archived contracts.

include_ledgers

boolean

Include credit 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:

CREDIT

data.product

object

required

Show child attributes

data.product.id

string<uuid>

required

data.product.name

string

required

data.contract

object

Show child attributes

data.contract.id

string<uuid>

required

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.

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

string

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

object[]

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

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

data.ledger.type

enum<string>

required

Available options:

CREDIT_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.rate_type

enum<string>

Available options:

COMMIT_RATE,

LIST_RATE

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

next_page

string | null

required

List commits

List balances

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

List credits

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Body

Response