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

The body is of type object.

Response

200 - application/json

Success

The response is of type object.

List commits

List balances

GET STARTED

API REFERENCE

List credits

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Body

Response