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

next_page

string | null

required

List commits

List balances

GET STARTED

ESSENTIALS

ENDPOINTS

List credits

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Body

Response