Metronome Credits and commits API
Credits and commits are used to manage customer balances.
OpenAPI Specification
openapi: 3.0.1
info:
title: Metronome Alerts Credits and commits API
version: 1.0.0
description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
servers:
- url: https://api.metronome.com
description: Production server
security:
- bearerAuth: []
tags:
- name: Credits and commits
description: Credits and commits are used to manage customer balances.
paths:
/v1/contracts/addManualBalanceLedgerEntry:
post:
description: 'Manually adjust the available balance on a commit or credit. This entry is appended to the commit ledger as a new event. Optionally include a description that provides the reasoning for the entry.
### Use this endpoint to:
- Address incorrect usage burn-down caused by malformed usage or invalid config
- Decrease available balance to account for outages where usage may have not been tracked or sent to Metronome
- Issue credits to customers in the form of increased balance on existing commit or credit
### Usage guidelines:
Manual ledger entries can be extremely useful for resolving discrepancies in Metronome. However, most corrections to inaccurate billings can be modified upstream of the commit, whether that is via contract editing, rate editing, or other actions that cause an invoice to be recalculated.
'
operationId: addManualBalanceLedgerEntry-v1
summary: Add a manual balance entry
tags:
- Credits and commits
requestBody:
description: Add a manual ledger entry to a balance
content:
application/json:
schema:
$ref: '#/components/schemas/AddManualBalanceLedgerEntryPayload'
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
contract_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
segment_id: 66368e29-3f97-4d15-a6e9-120897f0070a
amount: -1000
reason: Reason for entry
responses:
'200':
description: Success
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/contracts/customerCommits/list:
post:
description: "Retrieve all commit agreements for a customer, including both prepaid and postpaid commitments. This endpoint provides comprehensive visibility into contractual spending obligations, enabling you to track commitment utilization and manage customer contracts effectively.\n\n### Use this endpoint to:\n- Display commitment balances and utilization in customer dashboards\n- Track prepaid commitment drawdown and remaining balances\n- Monitor postpaid commitment progress toward minimum thresholds\n- Build commitment tracking and forecasting tools\n- Show commitment history with optional ledger details\n- Manage rollover balances between contract periods\n\n### Key response fields:\nAn array of Commit objects containing:\n- Commit type: PREPAID (pay upfront) or POSTPAID (pay at true-up)\n- Rate type: COMMIT_RATE (discounted) or LIST_RATE (standard pricing)\n- Access schedule: When commitment funds become available\n- Invoice schedule: When the customer is billed\n- Product targeting: Which product(s) usage is eligible to draw from this commit\n- Optional ledger entries: Transaction history (if `include_ledgers=true`)\n- Balance information: Current available amount (if `include_balance=true`)\n- Rollover settings: Fraction of unused amount that carries forward\n\n### Usage guidelines:\n- Pagination: Results limited to 25 commits per page; use 'next_page' for more\n- Date filtering options:\n - `covering_date`: Commits active on a specific date\n - `starting_at`: Commits with access on/after a date\n - `effective_before`: Commits with access before a date (exclusive)\n- Scope options:\n - `include_contract_commits`: Include contract-level commits (not just customer-level)\n - `include_archived`: Include archived commits and commits from archived contracts\n- Performance considerations:\n - include_ledgers: Adds detailed transaction history (slower)\n - include_balance: Adds current balance calculation (slower)\n- Optional filtering: Use commit_id to retrieve a specific commit\n"
operationId: listCustomerCommits-v1
summary: List commits
tags:
- Credits and commits
requestBody:
description: List all commits for a customer
content:
application/json:
schema:
type: object
required:
- customer_id
properties:
customer_id:
type: string
format: uuid
commit_id:
type: string
format: uuid
covering_date:
description: Include only commits that have access schedules that "cover" the provided date
type: string
format: date-time
starting_at:
description: Include only commits that have any access on or after the provided date
type: string
format: date-time
effective_before:
description: Include only commits that have any access before the provided date (exclusive)
type: string
format: date-time
include_contract_commits:
type: boolean
description: Include commits on the contract level.
include_archived:
type: boolean
description: Include archived commits and commits from archived contracts.
include_ledgers:
type: boolean
description: Include commit ledgers in the response. Setting this flag may cause the query to be slower.
include_balance:
type: boolean
description: Include the balance in the response. Setting this flag may cause the query to be slower.
next_page:
type: string
description: The next page token from a previous response.
limit:
type: integer
minimum: 1
maximum: 25
default: 25
description: The maximum number of commits to return. Defaults to 25.
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
commit_id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
include_ledgers: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- next_page
properties:
data:
type: array
items:
$ref: '#/components/schemas/Commit'
next_page:
type: string
nullable: true
example:
data:
- id: 62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35
type: PREPAID
rate_type: LIST_RATE
name: My test commit
description: My test commit description
priority: 100
product:
id: 2e30f074-d04c-412e-a134-851ebfa5ceb2
name: My product A
rollover_fraction: 0.1
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'
invoice_schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: f15e4e23-f74e-4de4-9b3a-8b07434116c4
invoice_id: 525b9759-7bbd-4a05-aab1-d7c43c976b57
amount: 10000000
unit_price: 10000000
quantity: 1
timestamp: '2020-03-01T00:00:00.000Z'
do_not_invoice: false
invoice_contract:
id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
ledger:
- invoice_id: 525b9759-7bbd-4a05-aab1-d7c43c976b57
amount: 10000000
timestamp: '2020-03-01T00:00:00.000Z'
type: PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION
segment_id: 2d45952c-5a6e-43a9-8aab-f61ee21be81a
uniqueness_key: 946g9bepi1-uniqueness-key
created_at: '2020-01-01T00:00:00.000Z'
next_page: null
/v1/contracts/customerCommits/create:
post:
description: "Creates customer-level commits that establish spending commitments for customers across their Metronome usage. Commits represent contracted spending obligations that can be either prepaid (paid upfront) or postpaid (billed later). \n\nNote: In most cases, you should add commitments directly to customer contracts using the contract/create or contract/edit APIs.\n\n### Use this endpoint to:\nUse this endpoint when you need to establish customer-level spending commitments that can be applied across multiple contracts or scoped to specific contracts. Customer-level commits are ideal for:\n- Enterprise-wide minimum spending agreements that span multiple contracts\n- Multi-contract volume commitments with shared spending pools\n- Cross-contract discount tiers based on aggregate usage\n\n#### Commit type Requirements: \n- You must specify either \"prepaid\" or \"postpaid\" as the commit type:\n- Prepaid commits: Customer pays upfront; invoice_schedule is optional (if omitted, creates a commit without an invoice)\n- Postpaid commits: Customer pays when the commitment expires (the end of the access_schedule); invoice_schedule is required and must match access_schedule totals. \n\n#### Billing configuration:\n- invoice_contract_id is required for postpaid commits and for prepaid commits with billing (only optional for free prepaid commits) unless do_not_invoice is set to true\n- For postpaid commits: access_schedule and invoice_schedule must have matching amounts\n- For postpaid commits: only one schedule item is allowed in both schedules.\n\n#### Scoping flexibility:\nCustomer-level commits can be configured in a few ways:\n- Contract-specific: Use the `applicable_contract_ids` field to limit the commit to specific contracts\n- Cross-contract: Leave `applicable_contract_ids` empty to allow the commit to be used across all of the customer's contracts\n\n#### Product targeting:\nCommits can be scoped to specific products using applicable_product_ids, applicable_product_tags, or specifiers, or left unrestricted to apply to all products.\n\n#### Priority considerations:\nWhen multiple commits 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 commits are applied in the desired order.\n\n### Usage guidelines:\n⚠️ Preferred Alternative: In most cases, you should add commits directly to contracts using the create contract or edit contract APIs instead of creating customer-level commits. Contract-level commits provide better organization and are the recommended approach for standard use cases.\n"
operationId: createCustomerCommit-v1
summary: Create a commit
tags:
- Credits and commits
requestBody:
description: Create a commit
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerCommitPayload'
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
type: prepaid
name: My Commit
priority: 100
product_id: f14d6729-6a44-4b13-9908-9387f1918790
invoice_contract_id: e57d6929-c2f1-4796-a9a8-63cedefe848d
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'
invoice_schedule:
credit_type_id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
schedule_items:
- unit_price: 10000000
quantity: 1
timestamp: '2020-03-01T00:00:00.000Z'
do_not_invoice: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/contracts/customerCommits/updateEndDate:
post:
description: "Shortens the end date of a prepaid commit to terminate it earlier than originally scheduled. Use this endpoint when you need to cancel or reduce the duration of an existing prepaid commit. Only works with prepaid commit types and can only move the end date forward (earlier), not extend it. \n\n### Usage guidelines:\nTo extend commit end dates or make other comprehensive edits, use the 'edit commit' endpoint instead.\n"
operationId: updateCommitEndDate-v1
summary: Update the commit end date
tags:
- Credits and commits
requestBody:
description: Update the access or invoice end date of a commit
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCommitEndDatePayload'
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
commit_id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
access_ending_before: '2020-01-01T00:00:00.000Z'
invoices_ending_before: '2020-01-01T00:00:00.000Z'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/contracts/commits/threshold-billing/release:
post:
description: 'If using threshold billing with an external payment gateway, Metronome does not facilitate the payment gating process on behalf of the client. As a result, clients must facilitate the transaction themselves. This end-point is used to either release or cancel the commit pending on the outcome of the external payment attempt.
To release the commit, you must pass the `workflow_id` provided in the `payment_gate.external_initiate` webhook.
### Use this endpoint to:
Facilitate payment gating workflows for threshold billing if using a payment gateway Metronome does not support today.
### Usage guidelines:
Ensure that you are set up to consume the `payment_gate.external_initiate` webhook and save the `workflow_id`.
'
operationId: releaseExternalPaymentGateThresholdCommit-v1
summary: Release external payment gate threshold commit
tags:
- Credits and commits
requestBody:
description: Information to identify the workflow that is in progress to release the commit, and what action we should take to complete the workflow.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPaymentGateThresholdCommitPayload'
example:
workflow_id: 5576ba1f-4a33-b473-3f05-6162d87b4a33
outcome: paid
responses:
'200':
description: Success
/v1/contracts/commits/disableTrueup:
post:
description: 'Disable the true-up invoice for a postpaid commit. If used, the true-up invoice will not be generated.
For postpaid commits, usage during the access period is paid for in arrears. If the total amount paid during the access period is less than the committed amount, there''s a final true-up invoice on the invoice_date.
'
operationId: disableCommitTrueup-v1
summary: Disable trueup for commit
tags:
- Credits and commits
requestBody:
description: Information to identify the commit
content:
application/json:
schema:
$ref: '#/components/schemas/DisableCommitTrueupPayload'
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
commit_id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
contract_id: 7526bacf-f08a-47af-b473-bc57b88890e1
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/contracts/customerCredits/list:
post:
description: "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.\n\n### Use this endpoint to:\n- Display all available credits in customer billing dashboards\n- Show credit balances and expiration dates\n- Track credit usage history with optional ledger details\n- Build credit management and reporting tools\n- Monitor promotional credit utilization\n• Support customer inquiries about available credits\n\n### Key response fields:\nAn array of Credit objects containing:\n- Credit details: Name, priority, and which applicable products/tags it applies to\n- 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. \n- Access schedule: When credits become available and expire\n- Optional ledger entries: Transaction history (if `include_ledgers=true`)\n- Balance information: Current available amount (if `include_balance=true`)\n- Metadata: Custom fields and usage specifiers\n\n### Usage guidelines:\n- Pagination: Results limited to 25 commits per page; use next_page for more\n- Date filtering options:\n - `covering_date`: Credits active on a specific date\n - `starting_at`: Credits with access on/after a date\n - `effective_before`: Credits with access before a date (exclusive)\n- Scope options:\n - `include_contract_credits`: Include contract-level credits (not just customer-level)\n - `include_archived`: Include archived credits and credits from archived contracts\n- Performance considerations:\n - `include_ledgers`: Adds detailed transaction history (slower)\n - `include_balance`: Adds current balance calculation (slower)\n- Optional filtering: Use credit_id to retrieve a specific commit\n"
operationId: listCustomerCredits-v1
summary: List credits
tags:
- Credits and commits
requestBody:
description: List all credits for a customer
content:
application/json:
schema:
type: object
required:
- customer_id
properties:
customer_id:
type: string
format: uuid
credit_id:
type: string
format: uuid
covering_date:
description: Return only credits that have access schedules that "cover" the provided date
type: string
format: date-time
starting_at:
description: Include only credits that have any access on or after the provided date
type: string
format: date-time
effective_before:
description: Include only credits that have any access before the provided date (exclusive)
type: string
format: date-time
include_contract_credits:
type: boolean
description: Include credits on the contract level.
include_archived:
type: boolean
description: Include archived credits and credits from archived contracts.
include_ledgers:
type: boolean
description: Include credit ledgers in the response. Setting this flag may cause the query to be slower.
include_balance:
type: boolean
description: Include the balance in the response. Setting this flag may cause the query to be slower.
next_page:
type: string
description: The next page token from a previous response.
limit:
type: integer
minimum: 1
maximum: 25
default: 25
description: The maximum number of commits to return. Defaults to 25.
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
credit_id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
include_ledgers: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- next_page
properties:
data:
type: array
items:
$ref: '#/components/schemas/Credit'
next_page:
type: string
nullable: true
example:
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
/v1/contracts/customerCredits/create:
post:
description: "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.\n\n### Use this endpoint to:\nUse 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:\n- Customer onboarding incentives that apply globally\n- Flexible spending allowances that aren't tied to a single contract\n- Migration scenarios where you need to preserve existing customer balances\n\n#### Scoping flexibility: \nCustomer-level credits can be configured in two ways:\n- Contract-specific: Use the applicable_contract_ids field to limit the credit to specific contracts\n- Cross-contract: Leave applicable_contract_ids empty to allow the credit to be used across all of the customer's contracts\n\n#### Product Targeting: \nCredits can be scoped to specific products using `applicable_product_ids` or `applicable_product_tags`, or left unrestricted to apply to all products.\n\n#### Priority considerations: \nWhen 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.\n\n#### Access Schedule Required: \nYou 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.\n\n### Usage Guidelines:\n⚠️ 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.\n"
operationId: createCustomerCredit-v1
summary: Create a credit
tags:
- Credits and commits
requestBody:
description: Create a credit
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerCreditPayload'
example:
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'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/contracts/customerCredits/updateEndDate:
post:
description: "Shortens the end date of an existing customer credit to terminate it earlier than originally scheduled. Only allows moving end dates forward (earlier), not extending them. \n\nNote: To extend credit end dates or make comprehensive edits, use the 'edit credit' endpoint instead.\n"
operationId: updateCreditEndDate-v1
summary: Update the credit end date
tags:
- Credits and commits
requestBody:
description: Update the access end date of a credit
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCreditEndDatePayload'
example:
customer_id: 13117714-3f05-48e5-a6e9-a66093f13b4d
credit_id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
access_ending_before: '2020-01-01T00:00:00.000Z'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/contracts/customerBalances/list:
post:
description: 'Retrieve a comprehensive view of all available balances (commits and credits) for a customer. This endpoint provides real-time visibility into prepaid funds, postpaid commitments, promotional credits, and other balance types that can offset usage charges, helping you build transparent billing experiences.
### Use this endpoint to:
- Display current available balances in customer dashboards
- Verify available funds before approving high-usage operations
- Generate balance reports for finance teams
- Filter balances by contract or date ranges
### Key response fields:
An array of balance objects (all credits and commits) containing:
- Balance details: Current available amount for each commit or credit
- Metadata: Product associations, priorities, applicable date ranges
- Optional ledger entries: Detailed transaction history (if `include_ledgers=true`)
- Balance calculations: Including pending transactions and future-dated entries
- Custom fields: Any additional metadata attached to balances
### Usage guidelines:
- Use the [getNetBalance](https://docs.metronome.com/api-reference/credits-and-commits/get-the-net-balance-of-a-customer) endpoint to retrieve a single combined current balance
- Date filtering: Use `effective_before` to include only balances with access before a specific date (exclusive)
- Set `include_balance=true` for calculated balance amounts on each commit or credit
- Set `include_ledgers=true` for full transaction history
- Set `include_contract_balances = true` to see contract level balan
# --- truncated at 32 KB (120 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/metronome/refs/heads/main/openapi/metronome-credits-and-commits-api-openapi.yml