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

customer_id

string<uuid>

required

priority

number

required

If multiple credits or commits are applicable, the one with the lower priority will apply first.

product_id

string<uuid>

required

access_schedule

object

required

Schedule for distributing the credit to the customer.

Show child attributes

name

string

displayed on invoices

Minimum string length: 1

description

string

Used only in UI/API. It is not exposed to end customers.

applicable_product_ids

string<uuid>[]

Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products.

applicable_product_tags

string[]

Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products.

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. This field cannot be used together with applicable_product_ids or applicable_product_tags.

Show child attributes

applicable_contract_ids

string[]

Which contract the credit applies to. If not provided, the credit applies to all contracts.

custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

rate_type

enum<string>

Available options:

COMMIT_RATE,

commit_rate,

LIST_RATE,

list_rate

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

Response

Success

data

object

required

Show child attributes

Create a commit

List commits

⌘I