Create a credit

curl --request POST \
  --url https://api.metronome.com/v1/contracts/customerCredits/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "name": "My Credit",
  "priority": 100,
  "product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
  "access_schedule": {
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "schedule_items": [
      {
        "amount": 1000,
        "starting_at": "2020-01-01T00:00:00.000Z",
        "ending_before": "2020-02-01T00:00:00.000Z"
      }
    ]
  }
}'

{
  "data": {
    "id": "6162d87b-e5db-4a33-b7f2-76ce6ead4e85"
  }
}

Credits and commits

Create a credit

Creates customer-level credits that provide spending allowances or free credit balances for customers across their Metronome usage. Note: In most cases, you should add credits directly to customer contracts using the contract/create or contract/edit APIs.

Use this endpoint to:

Use this endpoint when you need to provision credits directly at the customer level that can be applied across multiple contracts or scoped to specific contracts. Customer-level credits are ideal for:

Customer onboarding incentives that apply globally
Flexible spending allowances that aren’t tied to a single contract
Migration scenarios where you need to preserve existing customer balances

Scoping flexibility:

Customer-level credits can be configured in two ways:

Contract-specific: Use the applicable_contract_ids field to limit the credit to specific contracts
Cross-contract: Leave applicable_contract_ids empty to allow the credit to be used across all of the customer’s contracts

Product Targeting:

Credits can be scoped to specific products using applicable_product_ids or applicable_product_tags, or left unrestricted to apply to all products.

Priority considerations:

When multiple credits are applicable, the one with the lower priority value will be consumed first. If there is a tie, contract level commits and credits will be applied before customer level commits and credits. Plan your priority scheme carefully to ensure credits are applied in the desired order.

Access Schedule Required:

You must provide an access_schedule that defines when and how much credit becomes available to the customer over time. This usually is aligned to the contract schedule or starts immediately and is set to expire in the future.

Usage Guidelines:

⚠️ Preferred Alternative: In most cases, you should add credits directly to contracts using the contract/create or contract/edit APIs instead of creating customer-level credits. Contract-level credits provide better organization, and are easier for finance teams to recognize revenue, and are the recommended approach for most use cases.

POST

contracts

customerCredits

create

Create a credit

curl --request POST \
  --url https://api.metronome.com/v1/contracts/customerCredits/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "name": "My Credit",
  "priority": 100,
  "product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
  "access_schedule": {
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "schedule_items": [
      {
        "amount": 1000,
        "starting_at": "2020-01-01T00:00:00.000Z",
        "ending_before": "2020-02-01T00:00:00.000Z"
      }
    ]
  }
}'

{
  "data": {
    "id": "6162d87b-e5db-4a33-b7f2-76ce6ead4e85"
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Create a credit

The body is of type object.

Response

Success

The response is of type object.

Create a commit

List commits

GET STARTED

API REFERENCE

Create a credit

Use this endpoint to:

Scoping flexibility:

Product Targeting:

Priority considerations:

Access Schedule Required:

Usage Guidelines:

Authorizations

Body

Response