> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Metronome

The Metronome connector lets your AI agent act in each user's Metronome account. Each user connects their own Metronome access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 104 tools.

**Authentication:** Bearer Token
**Categories:** Accounting & Finance
**Tools:** 104: 45 read, 44 write, 15 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=METRONOME)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Metronome connection

   In **AgentKit > Connections**, create a Metronome connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'metronome'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Metronome:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'metronome_audit_logs_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "metronome"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Metronome:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="metronome_audit_logs_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Metronome credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'metronome_audit_logs_list',
  toolInput: {},
  connector: 'metronome',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="metronome_audit_logs_list",
    tool_input={},
    connection_name="metronome",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `metronome_audit_logs_list`

List Audit Logs · Read-only

List audit log entries for actions in the account from the API, the app or automated processes, optionally by date range, resource type or resource ID.
Returns data (entries with id, timestamp, actor, request, resource_type, resource_id, action, status and description) and next_page.
Use this to see who changed what and when. Audit logs may take a few minutes to appear.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): RFC 3339 timestamp (exclusive). Cannot be used with 'next_page'. Example: 2026-02-01T00:00:00.000Z
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `resource_id` (`string`, optional): Optional parameter that can be used to filter which audit logs are returned. If you specify resource_id, you must also specify resource_type. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
- `resource_type` (`string`, optional): Optional parameter that can be used to filter which audit logs are returned. If you specify resource_type, you must also specify resource_id. Example: contract
- `sort` (`string`, optional): Sort order by timestamp, e.g. date_asc or date_desc. Defaults to date_asc. Example: date_asc. One of: `date_asc`, `date_desc`.
- `starting_on` (`string`, optional): RFC 3339 timestamp of the earliest audit log to return. Cannot be used with 'next_page'. Example: 2026-01-01T00:00:00.000Z

Example input: `{}`

### `metronome_balances_list`

List Customer Balances · Read-only

List a customer's balances: commits and credits, customer-level and optionally contract-level, with optional date filters, archived items, ledgers and current balance.
Returns data (commits and credits with id, type, name, priority, product, access_schedule, contract and, when requested, balance and ledger) and next_page.
Use this for a combined view of commits and credits. Use metronome_net_balance_get for one total, or metronome_commits_list and metronome_credits_list for one kind.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `access_type` (`string`, optional): Filters balances by how they are drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used. Example: SPEND. One of: `SPEND`, `QUANTITY`.
- `covering_date` (`string`, optional): Return only balances that have access schedules that "cover" the provided date. Example: 2026-01-15T00:00:00.000Z
- `effective_before` (`string`, optional): Include only balances that have any access before the provided date (exclusive) Example: 2026-02-01T00:00:00.000Z
- `exclude_zero_balances` (`boolean`, optional): Exclude balances with zero amounts from the response. Example: false
- `id` (`string`, optional): Return only the commit or credit with this ID. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `include_archived` (`boolean`, optional): Include archived credits and credits from archived contracts. Example: false
- `include_balance` (`boolean`, optional): Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. Example: false
- `include_contract_balances` (`boolean`, optional): Include balances on the contract level. Example: false
- `include_ledgers` (`boolean`, optional): Include ledgers in the response. Setting this flag may cause the query to be slower. Example: true
- `limit` (`integer`, optional): The maximum number of commits to return. Defaults to 25. Example: 25
- `next_page` (`string`, optional): The next page token from a previous response. Example: 0c34b75b47491b73db66d46737d9a87
- `starting_at` (`string`, optional): Include only balances that have any access on or after the provided date. Example: 2026-01-01T00:00:00.000Z
- `webhook_notification_id` (`string`, optional): Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_billable_metric_get`

Get Billable Metric · Read-only

Get one billable metric's full configuration.
Returns data with id, name, event_type_filter, property_filters, aggregation_type, aggregation_key, group_keys, sql, custom_fields and archived_at.
Use this when you have the metric ID. Use metronome_billable_metrics_list to find it.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `billable_metric_id` (`string`, required): Billable metric ID (a UUID). Get it from metronome_billable_metrics_list. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d

Example input: `{"billable_metric_id":"<billable_metric_id>"}`

### `metronome_billable_metrics_list`

List Billable Metrics · Read-only

List billable metrics (how usage events are filtered and aggregated) with their full configuration, optionally including archived ones.
Returns data (metrics with id, name, event_type_filter, property_filters, aggregation_type, aggregation_key, group_keys, sql, custom_fields and archived_at) and next_page.
Use this to find metrics for usage products. Use metronome_customer_billable_metrics_list for the metrics one customer is billed on.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `include_archived` (`boolean`, optional): If true, the list of returned metrics will include archived metrics. Example: false
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{}`

### `metronome_billing_providers_list`

List Billing Providers · Read-only

List the billing providers configured for the account and their delivery methods.
Returns data (entries with billing_provider, delivery_method, delivery_method_id and delivery_method_configuration) and next_page.
Use this to find delivery_method_id values for customer billing configurations and tax credentials.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `next_page` (`string`, optional): The cursor to the next page of results. Example: af26878a-de62-4a0d-9b77-3936f7c2b6d6

Example input: `{}`

### `metronome_commits_list`

List Commits · Read-only

List a customer's prepaid and postpaid commits, optionally one commit, contract-level commits, archived commits, ledgers and balances.
Returns data (commits with id, type, name, priority, product, access_schedule, invoice_schedule, contract and, when requested, ledger and balance) and next_page.
Use this to track commitment use. Use metronome_credits_list for credits and metronome_balances_list for both.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `access_type` (`string`, optional): Filters commits by how their balances are drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used. Example: SPEND. One of: `SPEND`, `QUANTITY`.
- `commit_id` (`string`, optional): Commit ID (a UUID). Get it from metronome_commits_list or metronome_balances_list. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `covering_date` (`string`, optional): Include only commits that have access schedules that "cover" the provided date. Example: 2026-01-15T00:00:00.000Z
- `effective_before` (`string`, optional): Include only commits that have any access before the provided date (exclusive) Example: 2026-02-01T00:00:00.000Z
- `include_archived` (`boolean`, optional): Include archived commits and commits from archived contracts. Example: false
- `include_balance` (`boolean`, optional): Include the balance in the response. Setting this flag may cause the query to be slower. Example: false
- `include_contract_commits` (`boolean`, optional): Include commits on the contract level. Example: false
- `include_ledgers` (`boolean`, optional): Include commit ledgers in the response. Setting this flag may cause the query to be slower. Example: true
- `limit` (`integer`, optional): The maximum number of commits to return. Defaults to 25. Example: 25
- `next_page` (`string`, optional): The next page token from a previous response. Example: 0c34b75b47491b73db66d46737d9a87
- `starting_at` (`string`, optional): Include only commits that have any access on or after the provided date. Example: 2026-01-01T00:00:00.000Z

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_contract_edit_history_get`

Get Contract Edit History · Read-only

List every edit made to a contract since it was created, whether through the app, the edit endpoint or other update endpoints.
Returns data (edits with id, timestamp, uniqueness_key and the added, updated and archived terms of each edit).
Use this to audit how a contract changed. Use metronome_contract_get for the contract's current terms.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_contract_get`

Get Contract · Read-only

Get one contract with its full terms: rate card, commits, credits, overrides, discounts, scheduled charges, subscriptions and billing configuration, optionally as of a past date.
Returns data with the contract (id, customer_id, name, rate_card_id, starting_at, ending_before, commits, credits, overrides, subscriptions and more).
Use this when you have the customer and contract IDs. Use metronome_contracts_list to find them. Including ledgers or balances makes the call slower.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `as_of_date` (`string`, optional): Optional RFC 3339 timestamp. Return the contract as of this date. Cannot be used with include_ledgers parameter. Example: 2026-01-15T00:00:00.000Z
- `include_balance` (`boolean`, optional): Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. Example: false
- `include_ledgers` (`boolean`, optional): Include commit/credit ledgers in the response. Setting this flag may cause the query to be slower. Cannot be used with as_of_date parameter. Example: false
- `webhook_notification_id` (`string`, optional): Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_contract_rate_schedule_get`

Get Contract Rate Schedule · Read-only

Get the effective rates for a contract at a point in time, combining its rate card, scheduled rate changes and the contract's overrides, optionally filtered by product or pricing group values.
Returns data (rates with product_id, product_name, starting_at, ending_before, entitled, list_rate, override_rate, commit_rate and billing_frequency) and next_page.
Use this to see what a specific customer pays. Use metronome_rate_card_rates_get for the rate card's list prices without contract overrides.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): ID of the contract to get the rate schedule for. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): ID of the customer for whose contract to get the rate schedule for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `at` (`string`, optional): optional timestamp which overlaps with the returned rate schedule segments. When not specified, the current timestamp will be used. Example: 2020-01-01T00:00:00.000Z
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `selectors` (`array`, optional): List of rate selectors, rates matching ANY of the selectors will be included in the response. Passing no selectors will result in all rates being returned. Example: [{"product_id": "d6300dbb-882e-4d2d-8dec-5125d16b65d0", "partial_pricing_group_values": {"region": "us-west-2", "cloud": "aws"}}]

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_contracts_list`

List Customer Contracts · Read-only

List a customer's contracts in chronological order, optionally only those active on a date or starting after a date, with archived contracts, balances or ledgers included on request.
Returns data (contracts with id, name, rate_card_id, starting_at, ending_before, commits, credits, overrides, subscriptions and more) and cursor.
Use this to find a customer's contracts. Use metronome_contract_get for one contract. Including ledgers or balances makes the call slower.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `covering_date` (`string`, optional): Optional RFC 3339 timestamp. Only include contracts active on the provided date. This cannot be provided if starting_at filter is provided. Example: 2026-01-15T00:00:00.000Z
- `cursor` (`string`, optional): Cursor from a previous response to fetch the next page of contracts. Example: 0c34b75b47491b73db66d46737d9a87
- `include_archived` (`boolean`, optional): Include archived contracts in the response. Example: false
- `include_balance` (`boolean`, optional): Include the balance of credits and commits in the response. Setting this flag may cause the response to be slower. Example: false
- `include_ledgers` (`boolean`, optional): Include commit/credit ledgers in the response. Setting this flag may cause the response to be slower. Example: false
- `limit` (`number`, optional): Max number of contracts to return per page. Range: 1-20. Default: 20. Example: 25
- `starting_at` (`string`, optional): Optional RFC 3339 timestamp. Only include contracts that started on or after this date. This cannot be provided if covering_date filter is provided. Example: 2026-01-01T00:00:00.000Z

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_credits_list`

List Credits · Read-only

List a customer's credits, optionally one credit, contract-level credits, archived credits, ledgers and balances.
Returns data (credits with id, name, priority, product, access_schedule, applicable products and, when requested, ledger and balance) and next_page.
Use this to see promotional and contract credits. Use metronome_commits_list for commits and metronome_balances_list for both.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `covering_date` (`string`, optional): Return only credits that have access schedules that "cover" the provided date. Example: 2026-01-15T00:00:00.000Z
- `credit_id` (`string`, optional): Credit ID (a UUID). Get it from metronome_credits_list or metronome_balances_list. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `effective_before` (`string`, optional): Include only credits that have any access before the provided date (exclusive) Example: 2026-02-01T00:00:00.000Z
- `include_archived` (`boolean`, optional): Include archived credits and credits from archived contracts. Example: false
- `include_balance` (`boolean`, optional): Include the balance in the response. Setting this flag may cause the query to be slower. Example: false
- `include_contract_credits` (`boolean`, optional): Include credits on the contract level. Example: false
- `include_ledgers` (`boolean`, optional): Include credit ledgers in the response. Setting this flag may cause the query to be slower. Example: true
- `limit` (`integer`, optional): The maximum number of commits to return. Defaults to 25. Example: 25
- `next_page` (`string`, optional): The next page token from a previous response. Example: 0c34b75b47491b73db66d46737d9a87
- `starting_at` (`string`, optional): Include only credits that have any access on or after the provided date. Example: 2026-01-01T00:00:00.000Z

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_custom_field_keys_list`

List Custom Field Keys · Read-only

List the active custom field keys, optionally only for some entity types (customer, contract, product, commit and others).
Returns data (keys with entity, key and enforce_uniqueness) and next_page.
Use this before setting custom field values with metronome_custom_field_values_set.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `entities` (`array`, optional): Optional list of entity types to return keys for. Example: ["customer"]
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{}`

### `metronome_customer_alert_get`

Get Customer Threshold Notification · Read-only

Get the current evaluation status of one threshold notification for one customer.
Returns data with alert (configuration), customer_status (ok, in_alarm or evaluating) and triggered_by.
Use this to check whether a customer is past a threshold. Use metronome_customer_alerts_list for all of a customer's alerts.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `alert_id` (`string`, required): The Metronome ID of the threshold notification. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
- `customer_id` (`string`, required): The Metronome ID of the customer. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
- `alert_specifiers` (`array`, optional): Can be used only with `low_remaining_contract_credit_and_commit_balance_reached` and `low_remaining_contract_credit_and_commit_percentage_reached` notifications. Used to filter the alert by the custom field key-value pair. Example: [{"custom_field_filters": [{"entity": "Contract", "key": "region", "value": "us-east-1"}]}]
- `custom_field_filters` (`array`, optional): Used to filter the alert by the custom field key-value pair. Example: [{"entity": "Contract", "key": "region", "value": "emea"}]
- `group_values` (`array`, optional): Only present for `spend_threshold_reached` notifications. Retrieve the notification for a specific group key-value pair. Example: [{"key": "region", "value": "us-east-1"}]
- `plans_or_contracts` (`string`, optional): When parallel threshold notifications are enabled during migration, this flag denotes whether to fetch notifications for plans or contracts. Example: PLANS. One of: `PLANS`, `CONTRACTS`.
- `seat_filter` (`object`, optional): Only allowed for `low_remaining_seat_balance_reached` notifications. This filters alerts by the seat group key-value pair. Example: {"seat_group_key": "seat_type", "seat_group_value": "engineer"}
- `webhook_notification_id` (`string`, optional): Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"alert_id":"<alert_id>","customer_id":"<customer_id>"}`

### `metronome_customer_alerts_list`

List Customer Threshold Notifications · Read-only

List the threshold notifications that apply to a customer with their current status, optionally filtered by alert status.
Returns data (entries with alert configuration, customer_status and triggered_by) and next_page.
Use this to see which alerts a customer has and whether they fired. Use metronome_customer_alert_get for one alert.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): The Metronome ID of the customer. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
- `alert_statuses` (`array`, optional): Optionally filter by threshold notification status. If absent, only enabled notifications will be returned. Example: ["enabled"]
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_customer_billable_metrics_list`

List Customer Billable Metrics · Read-only

List the billable metrics available for one customer, optionally only those on the customer's current contract or plan, and optionally including archived ones.
Returns data (metrics with id, name, aggregation, filters and group keys) and next_page.
Use this to see what a customer is metered on. Use metronome_billable_metrics_list for every metric in the account.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `include_archived` (`boolean`, optional): If true, the list of returned metrics will include archived metrics. Example: false
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `on_current_plan` (`boolean`, optional): If true, the list of metrics will be filtered to just ones that are on the customer's current plan. Example: false

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_customer_billing_configs_get`

Get Customer Billing Configurations · Read-only

Get the billing provider configurations set up for a customer, such as Stripe, AWS Marketplace or NetSuite delivery settings.
Returns data (configurations with id, billing_provider, configuration, delivery_method, delivery_method_id and archived_at).
Use this to find the billing provider configuration ID needed when creating a contract. Use metronome_customer_billing_configs_set to add one.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
- `include_archived` (`boolean`, optional): Set to true to also return archived billing provider configurations. Defaults to false. Example: false

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_customer_events_preview`

Preview Events on Invoices · Read-only

Preview how a set of usage events would change a customer's draft invoices under their current contracts, without ingesting the events.
Returns data (preview invoices with line_items, totals and billing periods).
Use this to test pricing or new events before sending them with metronome_events_ingest. Customers with SQL billable metrics are not supported.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `events` (`array`, required): Array of usage events to include in the preview calculation. Must contain at least one event in `merge` mode. Example: [{"event_type": "api_request", "timestamp": "2026-01-15T12:00:00Z", "properties": {"region": "us-east-1"}}]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `mode` (`string`, optional): Controls how the provided events are combined with existing usage data. Use `replace` to calculate the preview as if these are the only events for the customer, ignoring all historical usage. Use `merge` to combine these events with the customer's existing usage. Defaults to `replace`. Example: replace. One of: `replace`, `merge`.
- `skip_zero_qty_line_items` (`boolean`, optional): When `true`, line items with zero quantity are excluded from the response. Example: false

Example input: `{"customer_id":"<customer_id>","events":[{"event_type":"api_request","timestamp":"2026-01-15T12:00:00Z","properties":{"region":"us-east-1"}}]}`

### `metronome_customer_get`

Get Customer · Read-only

Get one Metronome customer by its Metronome customer ID.
Returns data with id, external_id, ingest_aliases, name, customer_config, custom_fields, created_at, updated_at, archived_at and current_billable_status.
Use this when you have the customer ID. Use metronome_customers_list to find a customer by ingest alias or other filters.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_customers_list`

List Customers · Read-only

List customers in the Metronome account, optionally filtered by ingest alias, customer IDs, Salesforce account IDs, Stripe customer ID or archived status.
Returns data (customers with id, external_id, ingest_aliases, name, customer_config, custom_fields, created_at, archived_at and current_billable_status) and next_page.
Use this to browse or look up customers. Use metronome_customer_get when you already have the customer ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_ids` (`array`, optional): Filter the customer list by customer_id. Up to 100 ids can be provided. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `ingest_alias` (`string`, optional): Filter the customer list by ingest_alias. Example: team@example.com
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `only_archived` (`boolean`, optional): Filter the customer list to only return archived customers. By default, only active customers are returned. Example: false
- `salesforce_account_ids` (`array`, optional): Filter the customer list by salesforce_account_id. Up to 100 ids can be provided. Example: ["0015000000XyZAB"]
- `stripe_customer_id` (`string`, optional): Filter the customer list by the stripe_customer_id of active Stripe billing provider configurations. A Stripe customer ID can be linked to multiple customers, so it may match more than one customer. Archiving a customer also archives its billing provider configurations, so archived customers generally won't match. Example: cus_PxYZ123

Example input: `{}`

### `metronome_events_search`

Search Usage Events · Read-only

Look up usage events from the last 34 days by transaction ID.
Returns events with id, customer_id, event_type, properties, timestamp, transaction_id, is_duplicate, processed_at, matched_customer and billable_metrics.
Use this to confirm ingested events matched a customer and billable metrics. Use metronome_usage_get for aggregated usage.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `transactionIds` (`array`, required): The transaction IDs of the events to retrieve. Example: ["sktest-txn-0001"]

Example input: `{"transactionIds":["sktest-txn-0001"]}`

### `metronome_invoice_breakdowns_list`

List Invoice Breakdowns · Read-only

Break a customer's invoices into hourly or daily slices over a date range, so you can see how charges built up over the billing period.
Returns data (one invoice-shaped breakdown per window with line_items, total, start_timestamp and end_timestamp) and next_page.
Use this for time-series charge detail. Use metronome_invoices_list for whole invoices. Long ranges at hourly windows are slow; keep the range short.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `ending_before` (`string`, required): RFC 3339 timestamp. Breakdowns will only be returned for time windows that end on or before this time. Example: 2026-01-03T00:00:00.000Z
- `starting_on` (`string`, required): RFC 3339 timestamp. Breakdowns will only be returned for time windows that start on or after this time. Example: 2026-01-01T00:00:00.000Z
- `credit_type_id` (`string`, optional): Only return invoices for the specified credit type. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
- `limit` (`integer`, optional): Max number of results that should be returned. For daily breakdowns, the response can return up to 35 days worth of breakdowns. For hourly breakdowns, the response can return up to 24 hours. If there are more results, a cursor to the next page is returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `skip_zero_qty_line_items` (`boolean`, optional): If set, all zero quantity line items will be filtered out of the response. Example: false
- `sort` (`string`, optional): Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. Example: date_asc. One of: `date_asc`, `date_desc`.
- `status` (`string`, optional): Invoice status, e.g. DRAFT or FINALIZED. Example: FINALIZED
- `window_size` (`string`, optional): The granularity of the breakdowns to return. Defaults to day. Example: day. One of: `hour`, `day`.

Example input: `{"customer_id":"<customer_id>","ending_before":"<ending_before>","starting_on":"2024-01-01T00:00:00Z"}`

### `metronome_invoice_get`

Get Invoice · Read-only

Get one invoice of a customer with its line items, applied credits, totals and billing period, draft or finalized.
Returns data with the invoice (id, type, status, contract_id, credit_type, line_items, total, start_timestamp, end_timestamp, issued_at, external_invoice).
Use this when you have the customer and invoice IDs. Use metronome_invoices_list to find them.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `invoice_id` (`string`, required): Invoice ID (a UUID). Get it from metronome_invoices_list. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
- `skip_zero_qty_line_items` (`boolean`, optional): If set, all zero quantity line items will be filtered out of the response. Example: false

Example input: `{"customer_id":"<customer_id>","invoice_id":"<invoice_id>"}`

### `metronome_invoices_list`

List Invoices · Read-only

List a customer's invoices, optionally filtered by status, type, contract, pricing unit or date range, and sorted by date.
Returns data (invoices with id, type, status, contract_id, credit_type, line_items, total, start_timestamp, end_timestamp and issued_at) and next_page.
Use this to browse billing history and draft invoices. Use metronome_invoice_get for one invoice and metronome_invoice_breakdowns_list for hourly or daily detail.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `contract_id` (`string`, optional): Only return invoices for the specified contract. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
- `credit_type_id` (`string`, optional): Only return invoices for the specified credit type. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
- `ending_before` (`string`, optional): RFC 3339 timestamp (exclusive). Invoices will only be returned for billing periods that end before this time. Example: 2026-02-01T00:00:00.000Z
- `include_historical_commit_invoices` (`boolean`, optional): When true, includes historical commit invoices alongside active invoices. Defaults to false. Example: false
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `skip_zero_qty_line_items` (`boolean`, optional): If set, all zero quantity line items will be filtered out of the response. Example: false
- `sort` (`string`, optional): Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. Example: date_asc. One of: `date_asc`, `date_desc`.
- `starting_on` (`string`, optional): RFC 3339 timestamp (inclusive). Invoices will only be returned for billing periods that start at or after this time. Example: 2026-01-01T00:00:00.000Z
- `status` (`string`, optional): Invoice status, e.g. DRAFT, FINALIZED, or VOID. Example: FINALIZED
- `type` (`string`, optional): Filter invoices by type. Defaults to returning all invoice types. Example: USAGE. One of: `USAGE`, `USAGE_CONSOLIDATED`, `SCHEDULED`.
- `webhook_notification_id` (`string`, optional): Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_net_balance_get`

Get Customer Net Balance · Read-only

Get a customer's combined current balance across their credits and commits, optionally for one pricing unit, access type, or filtered set of balances.
Returns data with balance and credit_type_id.
Use this for a single remaining-balance number. Use metronome_balances_list to see each commit and credit.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): The ID of the customer. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `access_type` (`string`, optional): Filters balances by how they are drawn down. Defaults to `SPEND`. If set to `QUANTITY`, `credit_type_id` must not be provided. Example: SPEND. One of: `SPEND`, `QUANTITY`.
- `credit_type_id` (`string`, optional): The ID of the credit type (can be fiat or a custom pricing unit) to get the balance for. Defaults to USD (cents) if not specified. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
- `filters` (`array`, optional): Balance filters are OR'd together, so if a given commit or credit matches any of the filters, it will be included in the net balance. Example: [{"balance_types": ["CREDIT"], "custom_fields": {"campaign": "free-trial"}}, {"balance_types": ["PREPAID_COMMIT", "POSTPAID_COMMIT"], "custom_fields": {"campaign": "signup-promotion"}}]
- `invoice_inclusion_mode` (`string`, optional): Controls which invoices are considered when calculating the remaining balance. `FINALIZED` considers only deductions from finalized invoices. `FINALIZED_AND_DRAFT` also includes deductions from pending draft invoices. Example: FINALIZED_AND_DRAFT. One of: `FINALIZED`, `FINALIZED_AND_DRAFT`.

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_notification_get`

Get Offset Notification · Read-only

Get one offset lifecycle event notification by ID.
Returns data with id, name, type, policy, environment_type, created_at, created_by and archived_at.
Use this when you have the notification ID. Use metronome_offset_notifications_list to find it.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): The ID of the notification configuration to retrieve. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"id":"<id>"}`

### `metronome_offset_notifications_list`

List Offset Notifications · Read-only

List offset lifecycle event notifications, which fire at a set time before or after events such as a contract or commit starting or ending.
Returns data (notifications with id, name, type, policy, environment_type, created_at and archived_at) and cursor.
Use this to review custom notifications. Use metronome_system_notifications_list for built-in notification types.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `archive_filter` (`string`, optional): Filter options for the notification configurations. If not provided, defaults to NOT_ARCHIVED. Example: NOT_ARCHIVED. One of: `ARCHIVED`, `NOT_ARCHIVED`, `ALL`.
- `cursor` (`string`, optional): Cursor from the previous response's cursor field, to fetch the next page. Leave empty for the first page. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `limit` (`number`, optional): Maximum number of notifications to return (up to 400). Example: 50

Example input: `{}`

### `metronome_package_contracts_list`

List Contracts on Package · Read-only

List the contracts and customers that use a package, optionally only those active on a date or starting after a date.
Returns data (entries with customer_id, contract_id, starting_at, ending_before and archived_at) and next_page.
Use this to see who is on a package. Use metronome_contract_get for a contract's full terms.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `package_id` (`string`, required): Package ID (a UUID). Get it from metronome_packages_list. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `covering_date` (`string`, optional): Optional RFC 3339 timestamp. Only include contracts active on the provided date. This cannot be provided if starting_at filter is provided. Example: 2026-01-15T00:00:00.000Z
- `include_archived` (`boolean`, optional): Default false. Determines whether to include archived contracts in the results. Example: false
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `starting_at` (`string`, optional): Optional RFC 3339 timestamp. Only include contracts that started on or after this date. This cannot be provided if covering_date filter is provided. Example: 2026-01-01T00:00:00.000Z

Example input: `{"package_id":"<package_id>"}`

### `metronome_package_get`

Get Package · Read-only

Get one package with its name, aliases, duration and contract terms.
Returns data with the package (id, name, rate_card_id, aliases, duration, commits, credits, overrides, scheduled_charges, subscriptions and billing settings).
Use this when you have the package ID. Use metronome_packages_list to find it.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `package_id` (`string`, required): Package ID (a UUID). Get it from metronome_packages_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc

Example input: `{"package_id":"<package_id>"}`

### `metronome_packages_list`

List Packages · Read-only

List contract packages (reusable contract templates), optionally including archived ones.
Returns data (packages with id, name, rate_card_id, aliases, duration, commits, credits, overrides, scheduled_charges and created_at) and next_page.
Use this to find a package to create contracts from. Use metronome_package_get for one package.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `archive_filter` (`string`, optional): Filter packages by archived status. Defaults to NOT_ARCHIVED. Example: ARCHIVED. One of: `ARCHIVED`, `NOT_ARCHIVED`, `ALL`.
- `limit` (`integer`, optional): The maximum number of packages to return. Defaults to 10. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{}`

### `metronome_pricing_units_list`

List Pricing Units · Read-only

List pricing units (credit types): fiat currencies such as USD and any custom units such as AI credits.
Returns data (pricing units with id, name and is_currency) and next_page.
Use this to find credit_type_id values for rates, commits, credits and alerts.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{}`

### `metronome_product_get`

Get Product · Read-only

Get one product with its current configuration and the history of scheduled changes.
Returns data with the product (id, type, current, initial, updates, custom_fields and archived_at).
Use this when you have the product ID. Use metronome_products_list to find it.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Product ID (a UUID). Get it from metronome_products_list. Example: d84e7f4e-7a70-4fe4-be02-7a5027beffcc

Example input: `{"id":"<id>"}`

### `metronome_products_list`

List Products · Read-only

List products (the line items you bill for), with archived products excluded unless requested.
Returns data (products with id, type, current and initial configuration, updates, custom_fields and archived_at) and next_page.
Use this to find product IDs for rates, commits and credits. Use metronome_product_get for one product.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `archive_filter` (`string`, optional): Filter options for the product list. If not provided, defaults to not archived. Example: NOT_ARCHIVED. One of: `ARCHIVED`, `NOT_ARCHIVED`, `ALL`.
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{}`

### `metronome_rate_card_get`

Get Rate Card · Read-only

Get one rate card's name, description, pricing unit, credit type conversions, aliases and custom fields.
Returns data with the rate card (id, name, description, fiat_credit_type, credit_type_conversions, aliases, custom_fields, created_at).
Use this when you have the rate card ID. It does not return prices: use metronome_rate_card_rates_get for those.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: f3d51ae8-f283-44e1-9933-a3cf9ad7a6fe

Example input: `{"id":"<id>"}`

### `metronome_rate_card_rates_get`

Get Rate Card Rates · Read-only

Get the rates on a rate card at one point in time, optionally filtered by product, product tags or pricing group values.
Returns data (rates with product_id, product_name, starting_at, ending_before, entitled, rate, commit_rate, pricing_group_values and billing_frequency) and next_page.
Use this for list prices at a given time. Use metronome_rate_card_schedule_get for scheduled changes over a range, and metronome_contract_rate_schedule_get for a customer's own rates.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `at` (`string`, required): inclusive starting point for the rates schedule. Example: 2024-01-01T00:00:00.000Z
- `rate_card_id` (`string`, required): ID of the rate card to get the schedule for. Example: f3d51ae8-f283-44e1-9933-a3cf9ad7a6fe
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `selectors` (`array`, optional): List of rate selectors, rates matching ANY of the selector will be included in the response Passing no selectors will result in all rates being returned. Example: [{"product_id": "d6300dbb-882e-4d2d-8dec-5125d16b65d0", "partial_pricing_group_values": {"region": "us-west-2", "cloud": "aws"}}]

Example input: `{"at":"<at>","rate_card_id":"<rate_card_id>"}`

### `metronome_rate_card_schedule_get`

Get Rate Card Schedule · Read-only

Get a rate card's rate schedule from a start date, including future scheduled changes, optionally up to an end date and filtered by product or pricing group values.
Returns data (rates with product_id, product_name, starting_at, ending_before, entitled, rate, commit_rate and billing_frequency) and next_page.
Use this to see how prices change over time. Use metronome_rate_card_rates_get for the prices at a single moment.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `rate_card_id` (`string`, required): ID of the rate card to get the schedule for. Example: f3d51ae8-f283-44e1-9933-a3cf9ad7a6fe
- `starting_at` (`string`, required): inclusive starting point for the rates schedule. Example: 2024-01-01T00:00:00.000Z
- `ending_before` (`string`, optional): optional exclusive end date for the rates schedule. When not specified rates will show all future schedule segments. Example: 2026-02-01T00:00:00.000Z
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `selectors` (`array`, optional): List of rate selectors, rates matching ANY of the selector will be included in the response Passing no selectors will result in all rates being returned. Example: [{"product_id": "d6300dbb-882e-4d2d-8dec-5125d16b65d0", "partial_pricing_group_values": {"region": "us-west-2", "cloud": "aws"}}]

Example input: `{"rate_card_id":"<rate_card_id>","starting_at":"<starting_at>"}`

### `metronome_rate_cards_list`

List Rate Cards · Read-only

List rate cards (the price lists contracts are based on).
Returns data (rate cards with id, name, description, fiat_credit_type, credit_type_conversions, aliases and custom_fields) and next_page.
Use this to find a rate card ID. It does not return prices: use metronome_rate_card_rates_get or metronome_rate_card_schedule_get for those.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{}`

### `metronome_seat_balances_list`

List Seat Balances · Read-only

List seat-level balances for the seat-based subscriptions on a contract, optionally for given subscriptions or seats and with the underlying commits, credits and ledgers.
Returns data (seats with seat_id, balances and, when requested, commits and credits) and pagination.
Use this when credits or commits are allocated per seat. Use metronome_balances_list for customer and contract balances.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): The contract ID to retrieve seat balances for. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): The customer ID to retrieve seat balances for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `covering_date` (`string`, optional): Include only commits or credits with access that cover this specific date (cannot be used with starting_at or ending_before). Example: 2024-03-01T00:00:00.000Z
- `cursor` (`string`, optional): Page token from a previous response to retrieve the next page. Example: 0c34b75b47491b73db66d46737d9a87
- `effective_before` (`string`, optional): Include only commits or credits with access effective on or before this date (cannot be used with covering_date). Example: 2026-02-01T00:00:00.000Z
- `include_credits_and_commits` (`boolean`, optional): Include credits and commits in the response. Example: true
- `include_ledgers` (`boolean`, optional): Include ledger entries for each commit and commit. `include_credits_and_commits` must be set to `true` for `include_ledgers=true` to apply. Example: true
- `limit` (`integer`, optional): Maximum number of seats to return. Range: 1-100. Default: 25. When `include_credits_and_commits = true`, if the total commits/credits across all seats exceeds 100, a limit of 100 applies to the total credits and commits. Seats are included greedily to maximize the number of seats returned. Example: if seat 1 has 98 commits and seat 2 has 10 commits, both seats will be returned (total: 108 commits). Each returned seat includes all of its associated credits and commits.
- `seat_ids` (`array`, optional): Optional filter to only include specific seats. Example: ["seat-alice"]
- `skip_missing_seat_ids` (`boolean`, optional): When true, any seat_ids not found in contract subscriptions will be silently omitted from the response instead of returning a 400 error. Example: false
- `starting_at` (`string`, optional): Include only commits or credits with access effective on or after this date (cannot be used with covering_date). Example: 2026-01-01T00:00:00.000Z
- `subscription_ids` (`array`, optional): Optional filter to only include seats from specific subscriptions. If subscriptions ids are not mapped to SEAT_BASED subscriptions, error will be returned. Example: ["8deed800-1b7a-495d-a207-6c52bac54dc9"]

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_services_list`

List Services · Read-only

List Metronome's services and their IP addresses for firewall allowlisting.
Returns services (each with name, ips and usage).
Use this to keep firewall allowlists up to date. New IPs usually appear about 30 days before they are used.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `metronome_subscription_quantity_history_get`

Get Subscription Quantity History · Read-only

Get the past changes in quantity and price for one subscription on a contract. Future scheduled changes are not included.
Returns data with subscription_id, the credit type IDs and history (quantity and price changes with their dates).
Use this to show a customer how their seat count changed. Use metronome_subscription_seats_history_get for assigned seat IDs, and metronome_contract_get for future changes.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `subscription_id` (`string`, required): ID of a subscription on the contract. Get it from the subscriptions array of metronome_contract_get. Example: 1a824d53-bde6-4d82-96d7-6347ff227d5c

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>","subscription_id":"<subscription_id>"}`

### `metronome_subscription_seats_history_get`

Get Subscription Seats History · Read-only

Get the seat schedule for one seat-based subscription on a contract over time, optionally for one date or a date range.
Returns data (periods with starting_at, ending_before, total_quantity and assigned_seat_ids) and next_page.
Use this to see which seats were assigned when. Use metronome_subscription_quantity_history_get for quantity and price history.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `subscription_id` (`string`, required): ID of a subscription on the contract. Get it from the subscriptions array of metronome_contract_get. Example: 1a824d53-bde6-4d82-96d7-6347ff227d5c
- `covering_date` (`string`, optional): Get the seats history segment for the covering date. Cannot be used with `starting_at` or `ending_before`. Example: 2024-01-15T00:00:00.000Z
- `cursor` (`string`, optional): Cursor for pagination. Use the value from the `next_page` field of the previous response to retrieve the next page of results. Example: 0c34b75b47491b73db66d46737d9a87
- `ending_before` (`string`, optional): Include seats history segments that are active at or before this timestamp. Use with `starting_at` to get a specific time range. If not set, there's no upper bound. Example: 2026-02-01T00:00:00.000Z
- `limit` (`integer`, optional): Maximum number of seat schedule entries to return. Defaults to 10. Required range: 1 <= x <= 10. Example: 10
- `starting_at` (`string`, optional): Include seats history segments that are active at or after this timestamp. Use with `ending_before` to get a specific time range. If not set, there's no lower bound. Example: 2026-01-01T00:00:00.000Z

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>","subscription_id":"<subscription_id>"}`

### `metronome_system_notifications_list`

List System Notification Types · Read-only

List Metronome's built-in system notification types and whether each is enabled.
Returns data (types with type, is_enabled and policy) and cursor.
Use this to see which lifecycle events can notify you. Use metronome_notification_edit to turn one on or off.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs: none.

Example input: `{}`

### `metronome_usage_get`

Get Usage · Read-only

Get aggregated usage for many customers and billable metrics over a date range, in hourly, daily or whole-range windows.
Returns data (rows with customer_id, billable_metric_id, billable_metric_name, start_timestamp, end_timestamp, value and groups) and next_page.
Use this for usage reports across customers. Use metronome_usage_grouped_list for one customer and metric broken down by a group key.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `ending_before` (`string`, required): Must be aligned to UTC midnight and at least one day after `starting_on`. Example: 2026-01-08T00:00:00.000Z
- `starting_on` (`string`, required): Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`. Example: 2026-01-01T00:00:00.000Z
- `window_size` (`string`, required): A window_size of "day" or "hour" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of "none" will return a single usage aggregate for the entirety of the specified period. Example: day. One of: `hour`, `day`, `none`.
- `billable_metrics` (`array`, optional): A list of billable metrics to fetch usage for. If absent, all billable metrics will be returned. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `customer_ids` (`array`, optional): A list of Metronome customer IDs to fetch usage for. If absent, usage for all customers will be returned. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{"ending_before":"<ending_before>","starting_on":"2024-01-01T00:00:00Z","window_size":"hour"}`

### `metronome_usage_grouped_list`

List Grouped Usage · Read-only

Get usage for one customer and one billable metric over time, broken down by a group key (for example region or model) with optional group filters.
Returns data (rows with starting_on, ending_before, group_key, group_value, group and value) and next_page.
Use this to analyze one customer's usage by dimension. Use metronome_usage_get for totals across many customers.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `billable_metric_id` (`string`, required): Billable metric ID (a UUID). Get it from metronome_billable_metrics_list. Example: 222796fd-d29c-429e-89b2-549fabda4ed6
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 04ca7e72-4229-4a6e-ab11-9f7376fccbcb
- `window_size` (`string`, required): A window_size of "day" or "hour" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of "none" will return a single usage aggregate for the entirety of the specified period. Example: day. One of: `hour`, `day`, `none`.
- `ending_before` (`string`, optional): Must be aligned to UTC midnight and at least one day after `starting_on`. Example: 2026-01-08T00:00:00.000Z
- `group_by` (`object`, optional): Use group_key and group_filters instead. Use a single group key to group by. Compound group keys are not supported. Example: {"key": "region", "values": ["us-east-1", "eu-west-1"]}
- `group_filters` (`object`, optional): Object mapping group keys to arrays of values to filter on. Only usage matching these filter values will be returned. Keys must be present in group_key. Omit a key or use an empty array to include all values for that dimension. The combined number of entries across all value arrays may not exceed 200. Example: {"region": ["us-east1", "us-west1"]}
- `group_key` (`array`, optional): Group key to group usage by. Supports both simple (single key) and compound (multiple keys) group keys. For simple group keys, provide a single key e.g. `["region"]`. For compound group keys, provide multiple keys e.g. `["region", "team"]`. For streaming metrics, the keys must be defined as a simple or compound group key on the billable metric. For compound group keys, all keys must match an exact compound group key definition — partial matches are not allowed. Cannot be used together with `group_by`. Example: ["region"]
- `limit` (`integer`, optional): Max number of results that should be returned. Example: 25
- `next_page` (`string`, optional): Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
- `starting_on` (`string`, optional): Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`. Example: 2026-01-01T00:00:00.000Z

Example input: `{"billable_metric_id":"<billable_metric_id>","customer_id":"<customer_id>","window_size":"hour"}`

### `metronome_webhook_deliveries_list`

List Webhook Deliveries · Read-only

List notifications sent to a webhook destination in the last 30 days, with their delivery attempts, optionally filtered by date, customer, notification type or status.
Returns data (entries with id, notification_type, customer_id, first_attempted_at, last_attempted_at, last_response_status_code and num_attempts) and next_page.
Use this to audit or debug webhook delivery. Use metronome_webhook_delivery_get for one notification's payload and attempts.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `start_date` (`string`, required): Earliest first attempt to include (inclusive), as an ISO 8601 timestamp. Include a timezone to avoid ambiguity during filtering, e.g. 2026-10-13T00:00:00Z. Must be within the last 30 days and before end_date. Example: 2026-10-13T00:00:00Z
- `webhook_id` (`string`, required): ID of the webhook destination. Only notifications from the same Metronome environment as your API token are returned. Example: eb3a41d4-ca42-4cc1-b184-d208ab56ed65
- `end_date` (`string`, optional): Upper bound on first attempt time (exclusive), as an ISO 8601 timestamp. Include a timezone to avoid ambiguity during filtering. Defaults to the current time. Must be after start_date and no more than 30 days later. Set explicitly and keep fixed when paginating. Example: 2026-10-14T00:00:00Z
- `filters` (`object`, optional): Values within a filter are matched with OR; different filters are combined with AND. Omit a filter to include all values. Passing an empty array returns no results. Example: {"notification_types": ["invoice.finalized"]}
- `limit` (`number`, optional): Maximum number of notifications per page. Defaults to 25; must be an integer from 1 to 100. Example: 25
- `next_page` (`string`, optional): Pagination cursor from the previous response. Omit for the first page. Pass unchanged in the request body with the same webhook_id, date range, and filters. Example: 0c34b75b47491b73db66d46737d9a87

Example input: `{"start_date":"<start_date>","webhook_id":"<webhook_id>"}`

### `metronome_webhook_delivery_get`

Get Webhook Delivery · Read-only

Get one triggered notification sent to a webhook destination, with its payload and every delivery attempt.
Returns data with id, webhook_id, customer_id, notification_type, notification_payload and attempts.
Use this to debug one delivery. Use metronome_webhook_deliveries_list to find triggered notification IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `triggered_notification_id` (`string`, required): ID of the triggered notification. Example: 4f98dc25-6be7-4b0c-b25b-946c19511c5d
- `webhook_id` (`string`, required): ID of the webhook destination. Only notifications from the same Metronome environment as your API token are returned. Example: eb3a41d4-ca42-4cc1-b184-d208ab56ed65

Example input: `{"triggered_notification_id":"<triggered_notification_id>","webhook_id":"<webhook_id>"}`

### `metronome_alert_create`

Create Threshold Notification · Write

Create a threshold notification (alert) that fires when a customer's spend, balance, invoice total or usage crosses a threshold, for one customer or all customers.
Returns data with the new alert id.
Use this to watch account health. Use metronome_customer_alerts_list to see a customer's alerts. Set uniqueness_key to make retries safe.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `alert_type` (`string`, required): Type of the threshold notification. Example: low_remaining_contract_credit_and_commit_balance_reached. One of: `spend_threshold_reached`, `monthly_invoice_total_spend_threshold_reached`, `usage_threshold_reached`, `low_remaining_days_for_commit_segment_reached`, `low_remaining_commit_balance_reached`, `low_remaining_commit_percentage_reached`, `low_remaining_days_for_contract_credit_segment_reached`, `low_remaining_contract_credit_balance_reached`, `low_remaining_contract_credit_percentage_reached`, `low_remaining_contract_credit_and_commit_balance_reached`, `low_remaining_contract_credit_and_commit_percentage_reached`, `invoice_total_reached`, `low_remaining_seat_balance_reached`.
- `name` (`string`, required): Name of the threshold notification. Example: Low balance warning
- `threshold` (`number`, required): Threshold value of the notification policy. Depending upon the notification type, this number may represent a financial amount, the days remaining, or a percentage reached. Example: 100
- `access_type` (`string`, optional): Filters the notification to commits/credits with this access type. Only supported for `low_remaining_commit_balance_reached`, `low_remaining_commit_percentage_reached`, `low_remaining_contract_credit_and_commit_balance_reached`, `low_remaining_contract_credit_and_commit_percentage_reached`, `low_remaining_contract_credit_balance_reached`, `low_remaining_contract_credit_percentage_reached`, and `low_remaining_seat_balance_reached` notifications. Credit type cannot be specified if using QUANTITY access type. Example: SPEND. One of: `SPEND`, `QUANTITY`.
- `alert_specifiers` (`array`, optional): Can be used only with `low_remaining_contract_credit_and_commit_balance_reached` and `low_remaining_contract_credit_and_commit_percentage_reached` notifications. Defines the commits and credits used to calculate the remaining balance or percentage. Example: [{"custom_field_filters": [{"entity": "Contract", "key": "region"}], "exclude": [{"custom_field_filters": [{"entity": "Contract", "key": "region", "value": "us-east-1"}]}]}]
- `billable_metric_id` (`string`, optional): For threshold notifications of type `usage_threshold_reached`, specifies which billable metric to track the usage for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `credit_grant_type_filters` (`array`, optional): An array of strings, representing a way to filter the credit grant this threshold notification applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance notifications. Example: ["enterprise"]
- `credit_type_id` (`string`, optional): ID of the credit's currency, defaults to USD. If the specific notification type requires a pricing unit/currency, find the ID in the Metronome app. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
- `custom_field_filters` (`array`, optional): A list of custom field filters for threshold notification types that support advanced filtering. Only present for contract invoices. Example: [{"entity": "Contract", "key": "region", "value": "emea"}]
- `customer_id` (`string`, optional): If provided, will create this threshold notification for this specific customer. To create a notification for all customers, do not specify a `customer_id`. Example: 4db51251-61de-4bfe-b9ce-495e244f3491
- `evaluate_on_create` (`boolean`, optional): If true, the threshold notification will evaluate immediately on customers that already meet the notification threshold. If false, it will only evaluate on future customers that trigger the threshold. Defaults to true. Example: false
- `group_values` (`array`, optional): Only present for `spend_threshold_reached` notifications. Scope notification to a specific group key on individual line items. Example: [{"key": "region", "value": "us-east-1"}]
- `invoice_types_filter` (`array`, optional): Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate. Example: ["SCHEDULED or USAGE"]
- `seat_filter` (`object`, optional): Required for `low_remaining_seat_balance_reached` notifications. The alert is scoped to this seat group key-value pair. Example: {"seat_group_key": "seat_type", "seat_group_value": "engineer"}
- `uniqueness_key` (`string`, optional): Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error. Example: sktest-contract-0001

Example input: `{"alert_type":"spend_threshold_reached","name":"<name>","threshold":100}`

### `metronome_anrok_token_upsert`

Upsert Anrok API Token · Write

Set the Anrok tax API token for billing provider delivery methods. Used for threshold billing today.
Returns data with success.
Use this to connect Anrok tax to Metronome. Get delivery method IDs from metronome_billing_providers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `anrok_api_token` (`string`, required): The Anrok API token that is added to the configuration. Example: s123/sak456/secret.789
- `delivery_method_ids` (`array`, required): The delivery method IDs of the billing provider configurations to update, can be found in the response of the `/listConfiguredBillingProviders` endpoint. Example: ["9a906ebb-fbc7-42e8-8e29-53bfd2db3aca"]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"anrok_api_token":"<anrok_api_token>","delivery_method_ids":["9a906ebb-fbc7-42e8-8e29-53bfd2db3aca"]}`

### `metronome_avalara_credentials_upsert`

Upsert Avalara Credentials · Write

Set the Avalara tax credentials (environment, username, password) for billing provider delivery methods. Used for PLG invoicing tax calculation.
Returns an empty object on success.
Use this to connect Avalara tax to Metronome. Get delivery method IDs from metronome_billing_providers_list. The password is sent to Metronome as given.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `avalara_environment` (`string`, required): The Avalara environment to use (SANDBOX or PRODUCTION). Example: PRODUCTION. One of: `PRODUCTION`, `SANDBOX`.
- `avalara_password` (`string`, required): Avalara account password, sent to Metronome in the request body. Treat tool inputs that carry it as sensitive. Example: my_password_123
- `avalara_username` (`string`, required): The username for the Avalara account. Example: test@metronome.com
- `delivery_method_ids` (`array`, required): The delivery method IDs of the billing provider configurations to update, can be found in the response of the `/listConfiguredBillingProviders` endpoint. Example: ["9a906ebb-fbc7-42e8-8e29-53bfd2db3aca"]
- `commit_transactions` (`boolean`, optional): Commit transactions if you want Metronome tax calculations used for reporting and tax filings. Example: true
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"avalara_environment":"PRODUCTION","avalara_password":"<avalara_password>","avalara_username":"<avalara_username>","delivery_method_ids":["9a906ebb-fbc7-42e8-8e29-53bfd2db3aca"]}`

### `metronome_balance_ledger_entry_create`

Add Manual Balance Entry · Write

Add a manual ledger entry to a commit or credit segment to raise or lower its available balance, with a reason.
Returns an empty response on success.
Use this for one-off balance corrections. Get the commit or credit ID and segment ID from metronome_balances_list with include_ledgers. Set uniqueness_key to make retries safe.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`number`, required): Amount to add to the segment. A negative number will draw down from the balance. Example: -1000
- `customer_id` (`string`, required): ID of the customer whose balance is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `id` (`string`, required): ID of the balance (commit or credit) to update. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `reason` (`string`, required): Reason for the manual adjustment. This will be displayed in the ledger. Example: Reason for entry
- `segment_id` (`string`, required): ID of the segment to update. Example: 66368e29-3f97-4d15-a6e9-120897f0070a
- `contract_id` (`string`, optional): ID of the contract to update. Leave blank to update a customer level balance. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `per_group_amounts` (`object`, optional): If using individually configured commits/credits attached to seat managed subscriptions, the amount to add for each seat. Must sum to total amount. Example: {"us-east-1": 50}
- `timestamp` (`string`, optional): RFC 3339 timestamp indicating when the manual adjustment takes place. If not provided, it will default to the start of the segment. Example: 2026-01-15T12:00:00.000Z
- `uniqueness_key` (`string`, optional): Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error. Example: sktest-contract-0001

Example input: `{"amount":-1000,"customer_id":"<customer_id>","id":"<id>","reason":"<reason>","segment_id":"<segment_id>"}`

### `metronome_billable_metric_create`

Create Billable Metric · Write

Create a billable metric that turns usage events into a billable quantity, either with event type and property filters plus an aggregation, or with a SQL query.
Returns data with the new billable metric id.
Use this before creating a usage product with metronome_product_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The display name of the billable metric. Example: API requests
- `aggregation_key` (`string`, optional): Specifies the type of aggregation performed on matching events. Required if `sql` is not provided. Example: cpu_hours
- `aggregation_type` (`string`, optional): Specifies the type of aggregation performed on matching events. Example: count. One of: `count`, `latest`, `max`, `sum`, `unique`.
- `custom_fields` (`object`, optional): Custom fields to attach to the billable metric. Example: {"key": "value"}
- `event_type_filter` (`object`, optional): An optional filtering rule to match the 'event_type' property of an event. Example: {"in_values": ["api_request"]}
- `group_keys` (`array`, optional): Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets. Example: [["region"], ["machine_type"]]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `property_filters` (`array`, optional): A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric. Example: [{"name": "cpu_hours", "exists": true}, {"name": "region", "exists": true, "in_values": ["EU", "NA"]}, {"name": "machine_type", "exists": true, "in_values": ["slow", "fast"]}]
- `sql` (`string`, optional): The SQL query associated with the billable metric. This field is mutually exclusive with aggregation_type, event_type_filter, property_filters, aggregation_key, and group_keys. If provided, these other fields must be omitted. Example: select customer_id, count(*) as value from events where event_type = 'api_request' group by customer_id

Example input: `{"name":"<name>"}`

### `metronome_billable_metric_update`

Update Billable Metric · Write

Rename a billable metric. Only the display name can be changed.
Returns data with the billable metric id.
Use this to fix a metric's name. To change how usage is measured, create a new metric with metronome_billable_metric_create.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `billable_metric_id` (`string`, required): Billable metric ID (a UUID). Get it from metronome_billable_metrics_list. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `name` (`string`, required): The new name of the metric. Example: CPU hours

Example input: `{"billable_metric_id":"<billable_metric_id>","name":"<name>"}`

### `metronome_billing_provider_set_up`

Set Up Billing Provider · Write

Set up an account-level AWS, Azure or GCP marketplace billing provider with its delivery method and configuration.
Returns data with the new delivery_method_id.
Use this once per marketplace integration. Then map customers to it with metronome_customer_billing_configs_set.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `billing_provider` (`string`, required): The billing provider set for this configuration. Example: aws_marketplace. One of: `aws_marketplace`, `azure_marketplace`, `gcp_marketplace`.
- `configuration` (`object`, required): Account-level configuration for the billing provider. The structure of this object is specific to the billing provider and delivery provider combination. See examples below. Example: {"aws_external_id": "47b4f6b7-e297-42e8-b175-331d933b402c", "aws_iam_role_arn": "arn:aws:iam::test"}
- `delivery_method` (`string`, required): The method to use for delivering invoices for this configuration. Example: direct_to_billing_provider. One of: `direct_to_billing_provider`, `aws_sqs`, `aws_sns`.
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"billing_provider":"aws_marketplace","configuration":{"aws_external_id":"47b4f6b7-e297-42e8-b175-331d933b402c","aws_iam_role_arn":"arn:aws:iam::test"},"delivery_method":"direct_to_billing_provider"}`

### `metronome_commit_create`

Create Customer Commit · Write

Create a customer-level prepaid or postpaid commit that can apply across contracts, with its product, priority, access schedule and optional invoice schedule.
Returns data with the new commit id.
Use this only for commits that span contracts or the whole customer. Use metronome_contract_edit (add_commits) for a commit on one contract. Set uniqueness_key to make retries safe.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `access_schedule` (`object`, required): Schedule for distributing the commit to the customer. For "POSTPAID" commits only one schedule item is allowed and amount must match invoice_schedule total. Example: {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 1000, "starting_at": "2026-01-01T00:00:00.000Z", "ending_before": "2027-01-01T00:00:00.000Z"}]}
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `priority` (`number`, required): If multiple credits or commits are applicable, the one with the lower priority will apply first. Example: 100
- `product_id` (`string`, required): ID of the fixed product associated with the commit. This is required because products are used to invoice the commit amount. Example: f14d6729-6a44-4b13-9908-9387f1918790
- `type` (`string`, required): PREPAID (the customer pays up front, usually with an invoice_schedule) or POSTPAID (the customer commits to spend and is billed a true-up for any shortfall). Example: PREPAID. One of: `PREPAID`, `POSTPAID`.
- `applicable_contract_ids` (`array`, optional): Which contract the commit applies to. If not provided, the commit applies to all contracts. Example: ["9b85c1c1-5238-4f2a-a409-61412905e1e1"]
- `applicable_product_ids` (`array`, optional): Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `applicable_product_tags` (`array`, optional): Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products. Example: ["compute"]
- `custom_fields` (`object`, optional): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
- `description` (`string`, optional): Used only in UI/API. It is not exposed to end customers. Example: Created by the Scalekit connector
- `invoice_contract_id` (`string`, optional): The contract that this commit will be billed on. This is required for "POSTPAID" commits and for "PREPAID" commits unless there is no invoice schedule above (i.e., the commit is 'free'), or if do_not_invoice is set to true. Example: e57d6929-c2f1-4796-a9a8-63cedefe848d
- `invoice_schedule` (`object`, optional): Required for "POSTPAID" commits: the true up invoice will be generated at this time and only one schedule item is allowed; the total must match accesss_schedule amount. Optional for "PREPAID" commits: if not provided, this will be a "complimentary" commit with no invoice. Example: {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 1000, "timestamp": "2026-01-01T00:00:00.000Z"}]}
- `name` (`string`, optional): displayed on invoices. Example: My Commit
- `netsuite_sales_order_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `rate_type` (`string`, optional): Which rate the commit or credit draws down at: COMMIT_RATE (the contract's commit price, if one is set) or LIST_RATE. Example: COMMIT_RATE. One of: `COMMIT_RATE`, `LIST_RATE`.
- `salesforce_opportunity_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `specifiers` (`array`, optional): 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`. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "product_tags": ["compute"]}]
- `uniqueness_key` (`string`, optional): 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. Example: sktest-contract-0001

Example input: `{"access_schedule":{},"customer_id":"<customer_id>","priority":100,"product_id":"<product_id>","type":"PREPAID"}`

### `metronome_commit_edit`

Edit Commit · Write

Edit a contract-level or customer-level commit: name, description, access or invoice schedule, applicable products or contracts, product, priority, rate type or hierarchy settings.
Returns data with the commit id.
Use this to change one commit. Use metronome_commit_end_date_update to only shorten it, and metronome_commit_archive to remove it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `commit_id` (`string`, required): ID of the commit to edit. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
- `customer_id` (`string`, required): ID of the customer whose commit is being edited. Example: 4c91c473-fc12-445a-9c38-40421d47023f
- `access_schedule` (`object`, optional): When the balance can be used and how much. Give a credit_type_id (pricing unit, defaults to USD) and schedule_items, each with an amount and a starting_at / ending_before window (RFC 3339, hour boundaries). A postpaid commit takes exactly one item whose amount matches its invoice schedule. Example: {"update_schedule_items": [{"id": "d5edbd32-c744-48cb-9475-a9bca0e6fa39", "ending_before": "2025-03-12T00:00:00Z"}]}
- `applicable_contract_ids` (`array`, optional): Which contracts the customer-level commit applies to. If set to null, the commit applies to all of the customer's contracts. This field cannot be edited for POSTPAID commits or contract-level commits. Example: ["9b85c1c1-5238-4f2a-a409-61412905e1e1"]
- `applicable_product_ids` (`array`, optional): Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `applicable_product_tags` (`array`, optional): Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products. Example: ["compute"]
- `description` (`string`, optional): Updated description for the commit. Example: Created by the Scalekit connector
- `hierarchy_configuration` (`object`, optional): Optional configuration for commit hierarchy access control. Example: {"child_access": {"type": "ALL"}}
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `invoice_contract_id` (`string`, optional): ID of contract to use for invoicing. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `invoice_schedule` (`object`, optional): When the customer is invoiced for a prepaid commit. Give a credit_type_id and either schedule_items (each with a timestamp and an amount, or unit_price and quantity) or a recurring_schedule. Set do_not_invoice to true to skip invoicing. Example: {"add_schedule_items": [{"timestamp": "2026-01-01T00:00:00.000Z"}], "update_schedule_items": [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]}
- `name` (`string`, optional): Updated name for the commit. Example: Standard
- `priority` (`number`, optional): If multiple commits are applicable, the one with the lower priority will apply first. Example: 100
- `product_id` (`string`, optional): Product ID (a UUID). Get it from metronome_products_list. Example: 2e30f074-d04c-412e-a134-851ebfa5ceb2
- `rate_type` (`string`, optional): If provided, updates the commit to use the specified rate type for current and future invoices. Previously finalized invoices will need to be voided and regenerated to reflect the rate type change. Example: LIST_RATE. One of: `LIST_RATE`, `COMMIT_RATE`.
- `specifiers` (`array`, optional): 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`. Instead, to target usage by product or product tag, pass those values in the body of `specifiers`. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "product_tags": ["compute"]}]

Example input: `{"commit_id":"<commit_id>","customer_id":"<customer_id>"}`

### `metronome_commit_end_date_update`

Update Commit End Date · Write

Move a prepaid commit's access end date or invoice schedule end date earlier, to end it before its original schedule.
Returns data with the commit id.
Use this to cut a prepaid commit short. It cannot extend a commit. Use metronome_commit_edit for other changes.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `commit_id` (`string`, required): ID of the commit to update. Only supports "PREPAID" commits. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `customer_id` (`string`, required): ID of the customer whose commit is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `access_ending_before` (`string`, optional): RFC 3339 timestamp indicating when access to the commit will end and it will no longer be possible to draw it down (exclusive). If not provided, the access will not be updated. Example: 2020-01-01T00:00:00.000Z
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `invoices_ending_before` (`string`, optional): RFC 3339 timestamp indicating when the commit will stop being invoiced (exclusive). If not provided, the invoice schedule will not be updated. Example: 2020-01-01T00:00:00.000Z

Example input: `{"commit_id":"<commit_id>","customer_id":"<customer_id>"}`

### `metronome_commit_trueup_disable`

Disable Commit True-Up · Write

Turn off the true-up invoice for a postpaid commit, so Metronome does not bill the unused commitment at the end of the term.
Returns data with the commit id.
Use this when a customer's shortfall on a postpaid commit is waived.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `commit_id` (`string`, required): ID of the commit to update. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `contract_id` (`string`, required): ID of the contract that the commit is on. Example: 7526bacf-f08a-47af-b473-bc57b88890e1
- `customer_id` (`string`, required): ID of the customer whose commit is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `amendment_id` (`string`, optional): If applicable, the amendment ID that the commit is on. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"commit_id":"<commit_id>","contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_contract_create`

Create Contract · Write

Create a contract for a customer: its rate card or package, start and end dates, and optional commits, credits, overrides, discounts, scheduled charges, subscriptions and billing configuration.
Returns data with the new contract id.
Use this to start billing a customer. Use metronome_contract_edit to change an existing contract. Set uniqueness_key so a retried call does not create a second contract.
Prerequisites: a customer (metronome_customer_create) and a rate card (metronome_rate_cards_list) or package (metronome_packages_list).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `starting_at` (`string`, required): inclusive contract start time. Example: 2026-01-01T00:00:00.000Z
- `billing_provider_configuration` (`object`, optional): The billing provider configuration associated with a contract. Provide either an ID or the provider and delivery method. Example: {"billing_provider": "stripe", "delivery_method": "direct_to_billing_provider"}
- `commits` (`array`, optional): Commits on the contract: amounts the customer agrees to spend. Each needs a type (PREPAID or POSTPAID), a product_id and an access_schedule; prepaid commits usually also have an invoice_schedule. Optional settings include name, priority (lower applies first), applicable products or tags, rate_type and rollover_fraction. Example: [{"type": "PREPAID", "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "name": "Prepaid commit", "access_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 10000, "starting_at": "2026-01-01T00:00:00.000Z", "ending_before": "2027-01-01T00:00:00.000Z"}]}, "invoice_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 10000, "timestamp": "2026-01-01T00:00:00.000Z"}]}}]
- `credit_type_conversion_overrides` (`array`, optional): Overrides the conversion rate for the custom pricing unit over the specified interval. Example: [{"custom_credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "fiat_per_custom_credit": 100, "starting_at": "2026-01-01T00:00:00.000Z"}]
- `credits` (`array`, optional): Credits on the contract: free balance granted to the customer. Each needs a product_id and an access_schedule. Optional settings include name, priority (lower applies first), applicable products or tags and rate_type. Example: [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "name": "Promotional credit", "access_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 500, "starting_at": "2026-01-01T00:00:00.000Z", "ending_before": "2026-04-01T00:00:00.000Z"}]}}]
- `custom_fields` (`object`, optional): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
- `discounts` (`array`, optional): This field's availability is dependent on your client's configuration. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "schedule": {"credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "schedule_items": [{"timestamp": "2026-01-01T00:00:00.000Z"}]}}]
- `ending_before` (`string`, optional): exclusive contract end time. Example: 2027-01-01T00:00:00.000Z
- `hierarchy_configuration` (`object`, optional): Parent-child (account hierarchy) settings: the parent contract and customer, who pays (SELF or PARENT), and how usage statements and balances behave between parent and child. Example: {"parent": {"contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payer": "SELF"}
- `multiplier_override_prioritization` (`string`, optional): Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first. If tiered overrides are used, prioritization must be explicit. Example: LOWEST_MULTIPLIER. One of: `LOWEST_MULTIPLIER`, `EXPLICIT`.
- `name` (`string`, optional): Display name for the contract. Example: Acme Corp 2026 agreement
- `net_payment_terms_days` (`number`, optional): Number of days after the invoice issue date that payment is due, for example 30 for net-30 terms. Example: 30
- `netsuite_sales_order_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `overrides` (`array`, optional): Contract-specific price changes on top of the rate card. Each needs a starting_at and a type: OVERWRITE (with overwrite_rate), MULTIPLIER (with multiplier, for example 0.9 for 10% off) or TIERED (with tiers). Target products with product_id, applicable_product_tags or override_specifiers. Example: [{"starting_at": "2026-01-01T00:00:00.000Z", "type": "MULTIPLIER", "multiplier": 0.9, "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2"}]
- `package_alias` (`string`, optional): Selects the package linked to the specified alias as of the contract's start date. Mutually exclusive with package_id. Example: startup-plan
- `package_customizations` (`object`, optional): Changes applied on top of the package when the contract is created from package_id or package_alias. Add terms with add_commits, add_credits, add_recurring_commits, add_recurring_credits, add_overrides, add_scheduled_charges, add_spend_trackers and add_subscriptions (each the same shape as the matching contract field). Replace settings with set_spend_threshold_configuration, set_prepaid_balance_threshold_configuration and set_billing_provider_configuration. Adjust package terms with modify_subscriptions (per-subscription starting quantity), modify_recurring_commits and modify_recurring_credits (values for CUSTOM_DATE anchors) and modify_usage_statement_schedule. Example: {"add_credits": [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "access_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 100, "starting_at": "2026-01-01T00:00:00.000Z", "ending_before": "2026-04-01T00:00:00.000Z"}]}}]}
- `package_id` (`string`, optional): If provided, provisions a customer on a package instead of creating a traditional contract. When specified, only customer_id, starting_at, package_id, uniqueness_key, transition, and custom_fields are allowed. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `prepaid_balance_threshold_configuration` (`object`, optional): Auto-recharge: when the prepaid balance falls to threshold_amount, buy a commit that tops it up to recharge_to_amount. Needs is_enabled, threshold_amount, recharge_to_amount, commit (product_id) and payment_gate_config (payment_gate_type NONE, STRIPE or EXTERNAL). Example: {"is_enabled": false, "threshold_amount": 100, "recharge_to_amount": 100, "commit": {"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payment_gate_config": {"payment_gate_type": "NONE"}}
- `professional_services` (`array`, optional): This field's availability is dependent on your client's configuration. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "unit_price": 100, "quantity": 100, "max_amount": 100}]
- `rate_card_alias` (`string`, optional): Selects the rate card linked to the specified alias as of the contract's start date. Example: standard-2026
- `rate_card_id` (`string`, optional): Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `recurring_commits` (`array`, optional): Commits that are created again each period. Each needs a product_id, priority, starting_at, access_amount (unit_price and quantity per period) and commit_duration (value and unit). Optional settings include recurrence_frequency, ending_before, proration, rollover_fraction and invoice_amount. Example: [{"access_amount": {"unit_price": 100}, "commit_duration": {"value": 100}, "priority": 100, "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "starting_at": "2026-01-01T00:00:00.000Z"}]
- `recurring_credits` (`array`, optional): Credits that are granted again each period. Each needs a product_id, priority, starting_at, access_amount (unit_price and quantity per period) and commit_duration (value and unit). Optional settings include recurrence_frequency, ending_before, proration and rollover_fraction. Example: [{"access_amount": {"unit_price": 100}, "commit_duration": {"value": 100}, "priority": 100, "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "starting_at": "2026-01-01T00:00:00.000Z"}]
- `reseller_royalties` (`array`, optional): This field's availability is dependent on your client's configuration. Example: [{"reseller_type": "AWS", "starting_at": "2026-01-01T00:00:00.000Z", "fraction": 100, "netsuite_reseller_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `revenue_system_configuration` (`object`, optional): The revenue system configuration associated with a contract. Provide either an ID or the provider and delivery method. Example: {"revenue_system_configuration_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "provider": "netsuite"}
- `salesforce_opportunity_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `scheduled_charges` (`array`, optional): One-off or scheduled fixed charges. Each needs a product_id and a schedule with credit_type_id and schedule_items (timestamp plus amount, or unit_price and quantity). Example: [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "name": "Onboarding fee", "schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"timestamp": "2026-01-01T00:00:00.000Z", "amount": 2500}]}}]
- `scheduled_charges_on_usage_invoices` (`string`, optional): Determines which scheduled and commit charges to consolidate onto the Contract's usage invoice. The charge's `timestamp` must match the usage invoice's `ending_before` date for consolidation to occur. This field cannot be modified after a Contract has been created. If this field is omitted, charges will appear on a separate invoice from usage charges. Example: ALL. One of: `ALL`.
- `spend_threshold_configuration` (`object`, optional): Threshold billing: invoice the customer whenever unbilled spend reaches threshold_amount. Needs is_enabled, threshold_amount, commit (product_id and optional name) and payment_gate_config (payment_gate_type NONE, STRIPE or EXTERNAL). Example: {"is_enabled": false, "threshold_amount": 100, "commit": {"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payment_gate_config": {"payment_gate_type": "NONE"}}
- `spend_trackers` (`array`, optional): Spend trackers to attach to this contract. Aliases must be unique within a contract. Example: [{"alias": "standard-2026", "credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "reset_frequency": "BILLING_PERIOD", "applicable_spend_specifiers": [{"spend_type": "COMMIT_PURCHASE", "sources": ["THRESHOLD_RECHARGE"]}]}]
- `subscriptions` (`array`, optional): Optional list of subscriptions to add to the contract. Example: [{"subscription_rate": {"billing_frequency": "MONTHLY", "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "collection_schedule": "ADVANCE", "proration": {"is_prorated": false, "invoice_behavior": "BILL_IMMEDIATELY"}}]
- `total_contract_value` (`number`, optional): This field's availability is dependent on your client's configuration. Example: 100
- `transition` (`object`, optional): Make this contract a renewal or supersede of an earlier one. type is RENEWAL or SUPERSEDE, from_contract_id is the contract being replaced, and future_invoice_behavior controls what happens to the old contract's future invoices. Example: {"type": "RENEWAL", "from_contract_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1"}
- `uniqueness_key` (`string`, optional): Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error. Example: sktest-contract-0001
- `usage_filter` (`object`, optional): Route only matching usage to this contract, for customers with several contracts: a group_key (an event property) and the group_values that belong to this contract, optionally from starting_at. Example: {"group_key": "region", "group_values": ["us-east-1"]}
- `usage_statement_schedule` (`object`, optional): How often usage statements (invoices) are generated. frequency is MONTHLY, QUARTERLY, ANNUAL or WEEKLY; day is FIRST_OF_MONTH, CONTRACT_START or CUSTOM_DATE (with billing_anchor_date). Example: {"frequency": "MONTHLY", "day": "FIRST_OF_MONTH"}

Example input: `{"customer_id":"<customer_id>","starting_at":"<starting_at>"}`

### `metronome_contract_edit`

Edit Contract · Write

Edit an existing contract: add, update or archive commits, credits, overrides, discounts, scheduled charges, subscriptions and spend trackers, rename it, or change its end date or payment terms.
Returns data with the contract id and the edit id.
Use this for most contract changes. Use metronome_contract_end_date_update to only change the end date, and metronome_contract_edit_history_get to see past edits.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): ID of the contract being edited. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): ID of the customer whose contract is being edited. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `add_billing_provider_configuration_update` (`object`, optional): Update the billing provider configuration on the contract. Example: {"billing_provider_configuration": {"billing_provider_configuration_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "billing_provider": "aws_marketplace"}, "schedule": {"effective_at": "START_OF_CURRENT_PERIOD"}}
- `add_commits` (`array`, optional): Commits to add to the contract. Each needs a type (PREPAID or POSTPAID), a product_id and an access_schedule (credit_type_id and schedule_items with amount, starting_at and ending_before); prepaid commits usually also have an invoice_schedule. Optional: name, priority, applicable products or tags, rate_type and rollover_fraction. Example: [{"type": "PREPAID", "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "access_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 5000, "starting_at": "2026-03-01T00:00:00.000Z", "ending_before": "2027-01-01T00:00:00.000Z"}]}, "invoice_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 5000, "timestamp": "2026-03-01T00:00:00.000Z"}]}}]
- `add_credit_type_conversion_overrides` (`array`, optional): Overrides the conversion rate for the custom pricing unit over the specified interval. Overrides added later take precedence when multiple are added over the same interval. Example: [{"custom_credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "fiat_per_custom_credit": 100, "starting_at": "2026-01-01T00:00:00.000Z"}]
- `add_credits` (`array`, optional): Credits to add to the contract. Each needs a product_id and an access_schedule (credit_type_id and schedule_items with amount, starting_at and ending_before). Optional: name, priority, applicable products or tags and rate_type. Example: [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "access_schedule": {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 250, "starting_at": "2026-03-01T00:00:00.000Z", "ending_before": "2026-06-01T00:00:00.000Z"}]}}]
- `add_discounts` (`array`, optional): Discounts to add. Each needs a product_id and a schedule with credit_type_id and schedule_items (timestamp plus amount, or unit_price and quantity). Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "schedule": {"credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "schedule_items": [{"timestamp": "2026-01-01T00:00:00.000Z"}]}}]
- `add_overrides` (`array`, optional): Contract-specific price changes on top of the rate card. Each needs a starting_at and a type: OVERWRITE (with overwrite_rate), MULTIPLIER (with multiplier, for example 0.9 for 10% off) or TIERED (with tiers). Target products with product_id, applicable_product_tags or override_specifiers. Example: [{"starting_at": "2026-03-01T00:00:00.000Z", "type": "MULTIPLIER", "multiplier": 0.8, "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2"}]
- `add_prepaid_balance_threshold_configuration` (`object`, optional): Auto-recharge: when the prepaid balance falls to threshold_amount, buy a commit that tops it up to recharge_to_amount. Needs is_enabled, threshold_amount, recharge_to_amount, commit (product_id) and payment_gate_config (payment_gate_type NONE, STRIPE or EXTERNAL). Example: {"is_enabled": false, "threshold_amount": 100, "recharge_to_amount": 100, "commit": {"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payment_gate_config": {"payment_gate_type": "NONE"}}
- `add_professional_services` (`array`, optional): This field's availability is dependent on your client's configuration. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "unit_price": 100, "quantity": 100, "max_amount": 100}]
- `add_recurring_commits` (`array`, optional): Commits that are created again each period. Each needs a product_id, priority, starting_at, access_amount (unit_price and quantity per period) and commit_duration (value and unit). Optional settings include recurrence_frequency, ending_before, proration, rollover_fraction and invoice_amount. Example: [{"access_amount": {"unit_price": 100}, "commit_duration": {"value": 100}, "priority": 100, "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "starting_at": "2026-01-01T00:00:00.000Z"}]
- `add_recurring_credits` (`array`, optional): Credits that are granted again each period. Each needs a product_id, priority, starting_at, access_amount (unit_price and quantity per period) and commit_duration (value and unit). Optional settings include recurrence_frequency, ending_before, proration and rollover_fraction. Example: [{"access_amount": {"unit_price": 100}, "commit_duration": {"value": 100}, "priority": 100, "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "starting_at": "2026-01-01T00:00:00.000Z"}]
- `add_reseller_royalties` (`array`, optional): Reseller royalties to add, for usage sold through a cloud marketplace reseller. Each needs a reseller_type (AWS, AWS_PRO_SERVICE, GCP or GCP_PRO_SERVICE), plus fraction, applicable products or tags, starting_at and the reseller-specific options. Example: [{"reseller_type": "AWS"}]
- `add_revenue_system_configuration_update` (`object`, optional): Update the revenue system configuration on the contract. Currently only supports adding a revenue system configuration to a contract that does not already have one. Example: {"revenue_system_configuration": {"revenue_system_configuration_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "provider": "netsuite"}, "schedule": {"effective_at": "START_OF_CURRENT_PERIOD"}}
- `add_scheduled_charges` (`array`, optional): One-off or scheduled fixed charges. Each needs a product_id and a schedule with credit_type_id and schedule_items (timestamp plus amount, or unit_price and quantity). Example: [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "schedule": {"schedule_items": [{"timestamp": "2020-02-15T00:00:00.000Z", "unit_price": 1000000, "quantity": 1}]}}]
- `add_spend_threshold_configuration` (`object`, optional): Threshold billing: invoice the customer whenever unbilled spend reaches threshold_amount. Needs is_enabled, threshold_amount, commit (product_id and optional name) and payment_gate_config (payment_gate_type NONE, STRIPE or EXTERNAL). Example: {"is_enabled": false, "threshold_amount": 100, "commit": {"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payment_gate_config": {"payment_gate_type": "NONE"}}
- `add_spend_trackers` (`array`, optional): Spend trackers to add to this contract. Aliases must be unique within a contract. Example: [{"alias": "standard-2026", "credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "reset_frequency": "BILLING_PERIOD", "applicable_spend_specifiers": [{"spend_type": "COMMIT_PURCHASE", "sources": ["THRESHOLD_RECHARGE"]}]}]
- `add_subscriptions` (`array`, optional): Optional list of subscriptions to add to the contract. Example: [{"subscription_rate": {"billing_frequency": "MONTHLY", "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "collection_schedule": "ADVANCE", "proration": {"is_prorated": false, "invoice_behavior": "BILL_IMMEDIATELY"}}]
- `allow_contract_ending_before_finalized_invoice` (`boolean`, optional): If true, allows setting the contract end date earlier than the end_timestamp of existing finalized invoices. Finalized invoices will be unchanged; if you want to incorporate the new end date, you can void and regenerate finalized usage invoices. Defaults to true. Example: false
- `archive_commits` (`array`, optional): IDs of commits to archive. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `archive_credits` (`array`, optional): IDs of credits to archive. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `archive_scheduled_charges` (`array`, optional): IDs of scheduled charges to archive. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `archive_spend_trackers` (`array`, optional): Aliases of spend trackers to archive. Example: ["monthly-spend"]
- `remove_overrides` (`array`, optional): IDs of overrides to remove. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `uniqueness_key` (`string`, optional): Optional uniqueness key to prevent duplicate contract edits. Example: sktest-edit-0001
- `update_commits` (`array`, optional): Changes to existing commits on the contract. Each needs the commit_id, plus the fields to change: name, description, access_schedule or invoice_schedule (add, update or remove schedule items), applicable products or tags, product_id, priority, rate_type or rollover_fraction. Example: [{"commit_id": "1f4d2b6e-8c3a-4f5e-9a7b-2c1d0e9f8a7b", "name": "Renamed commit"}]
- `update_contract_end_date` (`string`, optional): RFC 3339 timestamp indicating when the contract will end (exclusive). Example: 2027-01-01T00:00:00.000Z
- `update_contract_name` (`string`, optional): Value to update the contract name to. If not provided, the contract name will remain unchanged. Example: Acme Corp 2026 agreement (amended)
- `update_credits` (`array`, optional): Changes to existing credits on the contract. Each needs the credit_id, plus the fields to change: name, description, access_schedule (add, update or remove schedule items), applicable products or tags, product_id, priority, rate_type or rollover_fraction. Example: [{"credit_id": "1f4d2b6e-8c3a-4f5e-9a7b-2c1d0e9f8a7b", "name": "Renamed credit"}]
- `update_net_payment_terms_days` (`number`, optional): Number of days after issuance of invoice after which the invoice is due (e.g. Net 30). Example: 100
- `update_prepaid_balance_threshold_configuration` (`object`, optional): Changes to the contract's auto-recharge settings: is_enabled, threshold_amount, recharge_to_amount, commit or payment_gate_config. Example: {"is_enabled": false, "threshold_amount": 100}
- `update_recurring_commits` (`array`, optional): Edits to these recurring commits will only affect commits whose access schedules has not started. Expired commits, and commits with an active access schedule will remain unchanged. Example: [{"recurring_commit_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `update_recurring_credits` (`array`, optional): Edits to these recurring credits will only affect credits whose access schedules has not started. Expired credits, and credits with an active access schedule will remain unchanged. Example: [{"recurring_credit_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `update_scheduled_charges` (`array`, optional): Changes to existing scheduled charges. Each needs the scheduled_charge_id, plus a new invoice_schedule (add, update or remove schedule items) or netsuite_sales_order_id. Example: [{"scheduled_charge_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
- `update_spend_threshold_configuration` (`object`, optional): Changes to the contract's threshold billing settings: is_enabled, threshold_amount, commit or payment_gate_config. Example: {"is_enabled": false, "threshold_amount": 100}
- `update_subscriptions` (`array`, optional): Optional list of subscriptions to update. Example: [{"subscription_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_contract_end_date_update`

Update Contract End Date · Write

Set, move or remove a contract's end date. Ending early truncates terms and removes upcoming scheduled invoices; moving it later only extends the contract length.
Returns data with the contract id.
Use this to end a contract or extend it. Use metronome_contract_edit for other changes to the terms.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): ID of the contract to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): ID of the customer whose contract is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `allow_ending_before_finalized_invoice` (`boolean`, optional): If true, allows setting the contract end date earlier than the end_timestamp of existing finalized invoices. Finalized invoices will be unchanged; if you want to incorporate the new end date, you can void and regenerate finalized usage invoices. Defaults to true. Example: false
- `ending_before` (`string`, optional): RFC 3339 timestamp indicating when the contract will end (exclusive). If not provided, the contract will be updated to be open-ended. Example: 2020-01-01T00:00:00.000Z
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>"}`

### `metronome_contract_invoice_issue_date_update`

Update Invoice Issue Date · Write

Change the issue date of a DRAFT invoice on a contract without changing future billing periods. The new date cannot be after the contract end date.
Returns data with the invoice id.
Use this to reschedule a single draft invoice. Get invoice IDs from metronome_invoices_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): ID of the invoice to update. The invoice must still be in DRAFT status. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `issue_date` (`string`, required): RFC 3339 timestamp. This will be the new issue date of the invoice. It must not be after the end date of the contract. Example: 2020-01-01T00:00:00.000Z
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"invoice_id":"<invoice_id>","issue_date":"<issue_date>"}`

### `metronome_contract_usage_filter_set`

Set Contract Usage Filter · Write

Route usage to a contract by group key and values from a start date, for customers with several contracts that have overlapping rates.
Returns an empty response on success.
Use this when one customer has multiple contracts and usage must be split between them by a property such as region or project.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `group_key` (`string`, required): Event property used to route usage to this contract, for example region. Example: region
- `group_values` (`array`, required): Values of the group key whose usage goes to this contract. Example: ["us-east-1", "us-west-2"]
- `starting_at` (`string`, required): When the filter takes effect, RFC 3339 on an hour boundary. Example: 2026-02-01T00:00:00.000Z
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>","group_key":"<group_key>","group_values":["us-east-1","us-west-2"],"starting_at":"<starting_at>"}`

### `metronome_credit_create`

Create Customer Credit · Write

Create a customer-level credit (for example a promotional credit) with its product, priority and access schedule.
Returns data with the new credit id.
Use this only for credits that span contracts or the whole customer. Use metronome_contract_edit (add_credits) for a credit on one contract. Set uniqueness_key to make retries safe.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `access_schedule` (`object`, required): Schedule for distributing the credit to the customer. Example: {"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "schedule_items": [{"amount": 100, "starting_at": "2026-01-01T00:00:00.000Z", "ending_before": "2026-04-01T00:00:00.000Z"}]}
- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `priority` (`number`, required): If multiple credits or commits are applicable, the one with the lower priority will apply first. Example: 100
- `product_id` (`string`, required): Product ID (a UUID). Get it from metronome_products_list. Example: f14d6729-6a44-4b13-9908-9387f1918790
- `applicable_contract_ids` (`array`, optional): Which contract the credit applies to. If not provided, the credit applies to all contracts. Example: ["9b85c1c1-5238-4f2a-a409-61412905e1e1"]
- `applicable_product_ids` (`array`, optional): Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `applicable_product_tags` (`array`, optional): Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products. Example: ["compute"]
- `custom_fields` (`object`, optional): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
- `description` (`string`, optional): Used only in UI/API. It is not exposed to end customers. Example: Created by the Scalekit connector
- `name` (`string`, optional): displayed on invoices. Example: My Credit
- `netsuite_sales_order_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `rate_type` (`string`, optional): Which rate the commit or credit draws down at: COMMIT_RATE (the contract's commit price, if one is set) or LIST_RATE. Example: COMMIT_RATE. One of: `COMMIT_RATE`, `LIST_RATE`.
- `salesforce_opportunity_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `specifiers` (`array`, optional): 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`. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "product_tags": ["compute"]}]
- `uniqueness_key` (`string`, optional): 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. Example: sktest-contract-0001

Example input: `{"access_schedule":{},"customer_id":"<customer_id>","priority":100,"product_id":"<product_id>"}`

### `metronome_credit_edit`

Edit Credit · Write

Edit a contract-level or customer-level credit: name, description, access schedule, applicable products or contracts, product, priority, rate type or hierarchy settings.
Returns data with the credit id.
Use this to change one credit. Use metronome_credit_end_date_update to only shorten it, and metronome_credit_archive to remove it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `credit_id` (`string`, required): ID of the credit to edit. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
- `customer_id` (`string`, required): ID of the customer whose credit is being edited. Example: 4c91c473-fc12-445a-9c38-40421d47023f
- `access_schedule` (`object`, optional): When the balance can be used and how much. Give a credit_type_id (pricing unit, defaults to USD) and schedule_items, each with an amount and a starting_at / ending_before window (RFC 3339, hour boundaries). A postpaid commit takes exactly one item whose amount matches its invoice schedule. Example: {"update_schedule_items": [{"id": "d5edbd32-c744-48cb-9475-a9bca0e6fa39", "ending_before": "2025-03-12T00:00:00Z"}]}
- `applicable_contract_ids` (`array`, optional): Which contracts the customer-level credit applies to. If set to null, the credit applies to all of the customer's contracts. This field cannot be set on a contract-level credit. Example: ["9b85c1c1-5238-4f2a-a409-61412905e1e1"]
- `applicable_product_ids` (`array`, optional): Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `applicable_product_tags` (`array`, optional): Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products. Example: ["compute"]
- `description` (`string`, optional): Updated description for the credit. Example: Created by the Scalekit connector
- `hierarchy_configuration` (`object`, optional): Optional configuration for credit hierarchy access control. Example: {"child_access": {"type": "ALL"}}
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): Updated name for the credit. Example: Standard
- `priority` (`number`, optional): If multiple commits are applicable, the one with the lower priority will apply first. Example: 100
- `product_id` (`string`, optional): Product ID (a UUID). Get it from metronome_products_list. Example: 2e30f074-d04c-412e-a134-851ebfa5ceb2
- `rate_type` (`string`, optional): If provided, updates the credit to use the specified rate type for current and future invoices. Previously finalized invoices will need to be voided and regenerated to reflect the rate type change. Example: LIST_RATE. One of: `LIST_RATE`, `COMMIT_RATE`.
- `specifiers` (`array`, optional): 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`. Instead, to target usage by product or product tag, pass those values in the body of `specifiers`. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "product_tags": ["compute"]}]

Example input: `{"credit_id":"<credit_id>","customer_id":"<customer_id>"}`

### `metronome_credit_end_date_update`

Update Credit End Date · Write

Move a credit's access end date earlier, to end it before its original schedule.
Returns data with the credit id.
Use this to cut a credit short. It cannot extend a credit. Use metronome_credit_edit for other changes.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `access_ending_before` (`string`, required): RFC 3339 timestamp indicating when access to the credit will end and it will no longer be possible to draw it down (exclusive). Example: 2020-01-01T00:00:00.000Z
- `credit_id` (`string`, required): ID of the commit to update. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
- `customer_id` (`string`, required): ID of the customer whose credit is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"access_ending_before":"<access_ending_before>","credit_id":"<credit_id>","customer_id":"<customer_id>"}`

### `metronome_custom_field_key_create`

Create Custom Field Key · Write

Add a custom field key for an entity type, optionally requiring each value to be unique.
Returns an empty response on success.
Use this to allow a new custom field. Then set values with metronome_custom_field_values_set.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `enforce_uniqueness` (`boolean`, required): Set to true to require every value of this key to be unique across objects of the entity type. Example: false
- `entity` (`string`, required): Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customer. One of: `alert`, `billable_metric`, `charge`, `commit`, `contract_credit`, `contract_product`, `contract`, `customer`, `discount`, `invoice`, `professional_service`, `product`, `rate_card`, `scheduled_charge`, `subscription`, `package_commit`, `package_credit`, `package_subscription`, `package_scheduled_charge`.
- `key` (`string`, required): Name of the new custom field key. Example: region
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"enforce_uniqueness":true,"entity":"alert","key":"<key>"}`

### `metronome_custom_field_values_set`

Set Custom Field Values · Write

Set custom field values on one entity, overwriting matching keys and keeping the others. All values are set or none are; each is at most 200 characters.
Returns an empty response on success.
Use this to tag a customer, contract, product or other entity. The key must exist (metronome_custom_field_keys_list).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `custom_fields` (`object`, required): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"region": "emea", "tier": "gold"}
- `entity` (`string`, required): Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customer. One of: `alert`, `billable_metric`, `charge`, `commit`, `contract_credit`, `contract_product`, `contract`, `customer`, `discount`, `invoice`, `professional_service`, `product`, `rate_card`, `scheduled_charge`, `subscription`, `package_commit`, `package_credit`, `package_subscription`, `package_scheduled_charge`.
- `entity_id` (`string`, required): ID of the object (for example the customer ID or contract ID) whose custom field values you are changing. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"custom_fields":{"region":"emea","tier":"gold"},"entity":"alert","entity_id":"<entity_id>"}`

### `metronome_customer_alert_reset`

Reset Customer Threshold Notification · Write

Clear the state of one threshold notification for a customer and evaluate it again against current data.
Returns an empty response on success.
Use this after fixing data or changing the alert so its status is up to date.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `alert_id` (`string`, required): The Metronome ID of the threshold notification. Example: 5e8691bf-b22a-4672-922d-f80eee940f01
- `customer_id` (`string`, required): The Metronome ID of the customer. Example: 4c83caf3-8af4-44e2-9aeb-e290531726d9
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"alert_id":"<alert_id>","customer_id":"<customer_id>"}`

### `metronome_customer_billing_configs_set`

Set Customer Billing Configurations · Write

Create one or more billing provider configurations for customers. Each says which downstream system (for example Stripe or a cloud marketplace) collects payment or receives the invoice.
Returns data (the created configurations with id, billing_provider, customer_id, configuration and delivery_method_id).
Use this to connect an existing customer to a billing provider. Get account-level delivery method IDs from metronome_billing_providers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `data` (`array`, required): Billing provider configurations to create. Each needs a customer_id, a billing_provider (for example stripe, aws_marketplace, azure_marketplace, gcp_marketplace, netsuite) and a delivery_method_id (from metronome_billing_providers_list) or delivery_method, plus a provider-specific configuration object (for Stripe: stripe_customer_id and stripe_collection_method). Example: [{"customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "billing_provider": "stripe", "delivery_method": "direct_to_billing_provider", "configuration": {"stripe_customer_id": "cus_PxYZ123", "stripe_collection_method": "charge_automatically"}}]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"data":[{"customer_id":"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc","billing_provider":"stripe","delivery_method":"direct_to_billing_provider","configuration":{"stripe_customer_id":"cus_PxYZ123","stripe_collection_method":"charge_automatically"}}]}`

### `metronome_customer_config_update`

Update Customer Configuration · Write

Update a customer's integration configuration, currently the Salesforce account ID linked to the customer.
Returns an empty response on success.
Use this to link or unlink a Salesforce account. Use metronome_customer_name_update to rename the customer.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `salesforce_account_id` (`string`, optional): The Salesforce account ID for the customer. Example: 0015500001WO1ZiABL

Example input: `{"customer_id":"<customer_id>"}`

### `metronome_customer_create`

Create Customer · Write

Create a customer in Metronome, optionally with ingest aliases, an external ID, custom fields and billing provider configurations that say where invoices go or payment is collected.
Returns data with the new customer's id, external_id, ingest_aliases, name and custom_fields.
Use this to onboard a new customer before creating a contract with metronome_contract_create. An ingest alias that is already in use returns 409 Conflict.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): This will be truncated to 160 characters if the provided name is longer. Example: Acme Corp
- `custom_fields` (`object`, optional): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
- `customer_billing_provider_configurations` (`array`, optional): Billing provider configurations to create with the customer, which say where invoices are sent or payment is collected. Each needs a billing_provider (for example stripe, aws_marketplace, netsuite) and a delivery_method or delivery_method_id, plus a provider-specific configuration object (for Stripe: stripe_customer_id and stripe_collection_method). Example: [{"billing_provider": "stripe", "delivery_method": "direct_to_billing_provider", "configuration": {"stripe_customer_id": "cus_PxYZ123", "stripe_collection_method": "charge_automatically"}}]
- `customer_revenue_system_configurations` (`array`, optional): Revenue system configurations to create with the customer, for example NetSuite or Salesforce revenue recognition. Each needs a provider and a delivery_method or delivery_method_id, plus a provider-specific configuration object. Example: [{"provider": "netsuite", "delivery_method": "direct_to_billing_provider", "configuration": {"netsuite_customer_id": "12345"}}]
- `external_id` (`string`, optional): (deprecated, use ingest_aliases instead) an alias that can be used to refer to this customer in usage events. Example: acct_12345
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `ingest_aliases` (`array`, optional): Aliases that can be used to refer to this customer in usage events. Example: ["team@example.com", "acct_12345"]

Example input: `{"name":"<name>"}`

### `metronome_customer_dashboard_url_get`

Get Embeddable Customer Dashboard URL · Write

Generate a signed, iframe-ready URL for one of Metronome's customer dashboards (invoices, usage, or commits and credits), with optional display options and colors.
Returns data with the dashboard url.
Use this to embed a customer's billing view in your own app. The URL is customer-specific; do not share it with other customers.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 4db51251-61de-4bfe-b9ce-495e244f3491
- `dashboard` (`string`, required): The type of dashboard to retrieve. Example: invoices. One of: `invoices`, `usage`, `commits_and_credits`.
- `color_overrides` (`array`, optional): Optional list of colors to override. Example: [{"name": "Gray_dark", "value": "#ff0000"}]
- `dashboard_options` (`array`, optional): Optional dashboard specific options. Example: [{"key": "show_zero_usage_line_items", "value": "false"}, {"key": "invoice_status_filter", "value": "FINALIZED"}]

Example input: `{"customer_id":"<customer_id>","dashboard":"invoices"}`

### `metronome_customer_ingest_aliases_set`

Set Customer Ingest Aliases · Write

Replace the full list of ingest aliases on a customer. Usage events can name the customer by any of these aliases instead of the Metronome ID.
Returns an empty response on success.
Use this to map your own customer IDs to a Metronome customer. The list you send replaces the existing aliases, so include the ones to keep.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `ingest_aliases` (`array`, required): The complete list of ingest aliases for the customer. Usage events can name the customer by any of these instead of the Metronome ID. This list replaces the current aliases. Example: ["team@example.com", "acct_12345"]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"customer_id":"<customer_id>","ingest_aliases":["team@example.com","acct_12345"]}`

### `metronome_customer_name_update`

Update Customer Name · Write

Change a customer's display name, which appears on invoices and in the Metronome app.
Returns data with the updated customer (id, external_id, ingest_aliases, name, custom_fields).
Use this to rename a customer. Use metronome_customer_config_update for the Salesforce account ID and metronome_customer_ingest_aliases_set for ingest aliases.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `name` (`string`, required): The new name for the customer. This will be truncated to 160 characters if the provided name is longer. Example: Example, Inc.
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"customer_id":"<customer_id>","name":"<name>"}`

### `metronome_events_ingest`

Ingest Usage Events · Write

Send up to 100 usage events to Metronome. Each event names the customer (Metronome ID or ingest alias), an event type, a timestamp up to 34 days in the past, a unique transaction_id and properties.
Returns an empty response on success.
Use this to report usage for billing. Events with a transaction_id seen in the last 34 days are ignored, so retries are safe. Use metronome_events_search to check that events arrived.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `events` (`array`, required): Usage events to send, at most 100 per call. Each needs a transaction_id (unique; repeats within 34 days are ignored), a customer_id (Metronome ID or an ingest alias), an event_type, and a timestamp in RFC 3339 format no more than 34 days old. properties holds any event data your billable metrics filter or aggregate on. Example: [{"transaction_id": "sktest-txn-0001", "customer_id": "team@example.com", "event_type": "api_request", "timestamp": "2026-01-15T12:00:00Z", "properties": {"region": "us-east-1", "tokens": 1200}}]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"events":[{"transaction_id":"sktest-txn-0001","customer_id":"team@example.com","event_type":"api_request","timestamp":"2026-01-15T12:00:00Z","properties":{"region":"us-east-1","tokens":1200}}]}`

### `metronome_historical_invoices_create`

Create Historical Invoices · Write

Create usage invoices for past billing periods on contracts, with your own usage line items, quantities and date ranges. Preview mode validates them without creating anything.
Returns data (the created or previewed invoices with id, customer_id, contract_id, line_items, start_timestamp, end_timestamp, status and total).
Use this for billing migrations or to correct past periods. Run with preview true first. Created invoices can be finalized and sent to the customer's billing provider.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `invoices` (`array`, required): Invoices to create. Each needs customer_id, contract_id, credit_type_id, inclusive_start_date, exclusive_end_date, issue_date and usage_line_items (each with product_id, inclusive_start_date, exclusive_end_date and quantity, optionally per pricing group). Optional: billable_status, breakdown_granularity and custom_fields. Example: [{"customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "contract_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1", "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "inclusive_start_date": "2026-01-01T00:00:00.000Z", "exclusive_end_date": "2026-02-01T00:00:00.000Z", "issue_date": "2026-02-01T00:00:00.000Z", "usage_line_items": [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "inclusive_start_date": "2026-01-01T00:00:00.000Z", "exclusive_end_date": "2026-02-01T00:00:00.000Z", "quantity": 1000}]}]
- `preview` (`boolean`, required): Set to true to validate and return the invoices without creating them. Set to false to create them. Example: true
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"invoices":[],"preview":true}`

### `metronome_invoice_regenerate`

Regenerate Invoice · Write

Regenerate a voided invoice, recalculating it with current rates, available balances and fees.
Returns data with the new invoice id.
Use this after metronome_invoice_void once the underlying data or pricing is fixed. The new invoice can be finalized and sent to the customer's billing provider.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): The invoice id to regenerate. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `metronome_notification_create`

Create Offset Notification · Write

Create an offset lifecycle event notification that fires a set time before or after a lifecycle event. The event type comes from policy.type.
Returns data with the created notification (id, name, type, policy, created_at).
Use this to get advance warning of renewals or expirations. Set uniqueness_key to make retries safe.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The name for this offset notification configuration. Example: 7 days before contract start
- `policy` (`object`, required): The offset lifecycle event policy that defines when and how this notification should be triggered. The lifecycle event type is inferred from the policy.type field. Example: {"type": "contract.start", "offset": "-P7D"}
- `uniqueness_key` (`string`, optional): Optional uniqueness key to prevent duplicate notification configurations. Example: contract-start-notification-823j7fqzo1

Example input: `{"name":"<name>","policy":{"type":"contract.start","offset":"-P7D"}}`

### `metronome_notification_edit`

Edit Notification · Write

Edit an offset notification's policy or enabled state, or turn a system notification type on or off.
Returns data with the updated notification or system notification type.
Use this to change or toggle a notification. Use metronome_notification_archive to remove an offset notification.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `policy` (`object`, required): Updated policy configuration. The policy.type must match the existing lifecycle event type. Example: {"type": "contract.start", "offset": "P2D"}
- `id` (`string`, optional): The ID of the notification configuration to edit. Not provided when updating the configuration for system events. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `is_enabled` (`boolean`, optional): Set to true to enable webhook messages for the notification indicated in the policy, false to disable. Only supported by system lifecycle events. Example: false

Example input: `{"policy":{"type":"contract.start","offset":"P2D"}}`

### `metronome_package_create`

Create Package · Write

Create a package: a reusable set of time-relative contract terms (rate card, commits, credits, overrides, scheduled charges, subscriptions) to provision customers with standard pricing.
Returns data with the new package id.
Use this to define standard plans once and create contracts from them with metronome_contract_create (package_id or package_alias).
Prerequisite: a rate card (metronome_rate_cards_list).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Package name. Example: Startup plan
- `aliases` (`array`, optional): Reference this alias when creating a contract. If the same alias is assigned to multiple packages, it will reference the package to which it was most recently assigned. It is not exposed to end customers. Example: [{"name": "standard-2026"}]
- `billing_provider` (`string`, optional): Billing provider that contracts from this package are billed through, such as stripe or aws_marketplace. Example: stripe. One of: `aws_marketplace`, `azure_marketplace`, `gcp_marketplace`, `stripe`, `netsuite`.
- `commits` (`array`, optional): Commits included in contracts from this package. Same shape as contract commits, but times are relative offsets (for example starting_at_offset) from the contract start. Example: [{"type": "PREPAID", "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "access_schedule": {"schedule_items": [{"amount": 100, "starting_at_offset": {"value": 10, "unit": "DAYS"}, "duration": {"value": 10, "unit": "DAYS"}}]}}]
- `contract_name` (`string`, optional): Name given to contracts created from this package. Example: Startup plan contract
- `credits` (`array`, optional): Credits included in contracts from this package. Same shape as contract credits, but times are relative offsets from the contract start. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "access_schedule": {"schedule_items": [{"amount": 100, "starting_at_offset": {"value": 10, "unit": "DAYS"}, "duration": {"value": 10, "unit": "DAYS"}}]}}]
- `delivery_method` (`string`, optional): How invoices are delivered to the billing provider, such as direct_to_billing_provider. Example: direct_to_billing_provider. One of: `direct_to_billing_provider`, `aws_sqs`, `tackle`, `aws_sns`.
- `duration` (`object`, optional): How long contracts created from the package last: a value and a unit (DAYS, WEEKS, MONTHS, QUARTERS or YEARS). Leave empty for no end date. Example: {"value": 12, "unit": "MONTHS"}
- `multiplier_override_prioritization` (`string`, optional): Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first. If tiered overrides are used, prioritization must be explicit. Example: LOWEST_MULTIPLIER. One of: `LOWEST_MULTIPLIER`, `EXPLICIT`.
- `net_payment_terms_days` (`number`, optional): Number of days after the invoice issue date that payment is due, for example 30 for net-30 terms. Example: 30
- `overrides` (`array`, optional): Price overrides for contracts from this package. Each needs a type (OVERWRITE, MULTIPLIER or TIERED) and its rate, multiplier or tiers, plus the products it applies to; times are relative offsets from the contract start. Example: [{"starting_at_offset": {"value": 10, "unit": "DAYS"}, "override_specifiers": [{"commit_ids": ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"], "recurring_commit_ids": ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]}]}]
- `prepaid_balance_threshold_configuration` (`object`, optional): Auto-recharge: when the prepaid balance falls to threshold_amount, buy a commit that tops it up to recharge_to_amount. Needs is_enabled, threshold_amount, recharge_to_amount, commit (product_id) and payment_gate_config (payment_gate_type NONE, STRIPE or EXTERNAL). Example: {"is_enabled": false, "threshold_amount": 100, "recharge_to_amount": 100, "commit": {"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payment_gate_config": {"payment_gate_type": "NONE"}}
- `rate_card_alias` (`string`, optional): Selects the rate card linked to the specified alias as of the contract's start date. Example: standard-2026
- `rate_card_id` (`string`, optional): Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `recurring_commits` (`array`, optional): Commits that are created again each period. Each needs a product_id, priority, starting_at, access_amount (unit_price and quantity per period) and commit_duration (value and unit). Optional settings include recurrence_frequency, ending_before, proration, rollover_fraction and invoice_amount. Example: [{"access_amount": {"unit_price": 100}, "commit_duration": {"value": 100}, "priority": 100, "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "starting_at_offset": {"value": 10, "unit": "DAYS"}}]
- `recurring_credits` (`array`, optional): Credits that are granted again each period. Each needs a product_id, priority, starting_at, access_amount (unit_price and quantity per period) and commit_duration (value and unit). Optional settings include recurrence_frequency, ending_before, proration and rollover_fraction. Example: [{"access_amount": {"unit_price": 100}, "commit_duration": {"value": 100}, "priority": 100, "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "starting_at_offset": {"value": 10, "unit": "DAYS"}}]
- `scheduled_charges` (`array`, optional): Scheduled charges for contracts from this package. Each needs a product_id and a schedule; times are relative offsets from the contract start. Example: [{"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "schedule": {"schedule_items": [{"unit_price": 100, "quantity": 100, "date_offset": {"value": 10, "unit": "DAYS"}}]}}]
- `scheduled_charges_on_usage_invoices` (`string`, optional): Determines which scheduled and commit charges to consolidate onto the Contract's usage invoice. The charge's `timestamp` must match the usage invoice's `ending_before` date for consolidation to occur. This field cannot be modified after a Contract has been created. If this field is omitted, charges will appear on a separate invoice from usage charges. Example: ALL. One of: `ALL`.
- `spend_threshold_configuration` (`object`, optional): Threshold billing: invoice the customer whenever unbilled spend reaches threshold_amount. Needs is_enabled, threshold_amount, commit (product_id and optional name) and payment_gate_config (payment_gate_type NONE, STRIPE or EXTERNAL). Example: {"is_enabled": false, "threshold_amount": 100, "commit": {"product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "payment_gate_config": {"payment_gate_type": "NONE"}}
- `spend_trackers` (`array`, optional): Spend trackers for contracts from this package. Each needs an alias, a credit_type_id, a reset_frequency and applicable_spend_specifiers that say which spend counts. Example: [{"alias": "standard-2026", "credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "reset_frequency": "BILLING_PERIOD", "applicable_spend_specifiers": [{"spend_type": "COMMIT_PURCHASE", "sources": ["THRESHOLD_RECHARGE"]}]}]
- `subscriptions` (`array`, optional): Subscriptions for contracts from this package. Each needs a subscription_rate (product_id and billing_frequency), a collection_schedule (ADVANCE or ARREARS) and proration settings; starting times are relative to the contract start. Example: [{"subscription_rate": {"billing_frequency": "MONTHLY", "product_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}, "collection_schedule": "ADVANCE", "proration": {"is_prorated": false, "invoice_behavior": "BILL_IMMEDIATELY"}}]
- `uniqueness_key` (`string`, optional): Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error. Example: sktest-contract-0001
- `usage_statement_schedule` (`object`, optional): How often usage statements (invoices) are generated. frequency is MONTHLY, QUARTERLY, ANNUAL or WEEKLY; day is FIRST_OF_MONTH, CONTRACT_START or CUSTOM_DATE (with billing_anchor_date). Example: {"frequency": "MONTHLY"}

Example input: `{"name":"<name>"}`

### `metronome_pricing_unit_create`

Create Pricing Unit · Write

Create a custom pricing unit for charging in a non-fiat unit, for example AI credits.
Returns data with the new pricing unit id.
Use this before creating rate cards or credits in a custom unit.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The name of the custom pricing unit. This will appear on invoices. Example: AI credits
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>"}`

### `metronome_product_create`

Create Product · Write

Create a product, the basic unit of an invoice line item: a fixed, usage, subscription, composite or pro-services product, optionally tied to a billable metric.
Returns data with the new product id.
Use this before adding rates for it with metronome_rate_card_rate_add. Usage products need a billable_metric_id (metronome_billable_metrics_list).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): displayed on invoices. Example: API requests
- `type` (`string`, required): Product type: USAGE (billed from a billable metric), FIXED (flat fees, commits and credits), SUBSCRIPTION (recurring seat or license charges), COMPOSITE (a percentage of other products' spend) or PROFESSIONAL_SERVICE. Example: USAGE. One of: `FIXED`, `USAGE`, `COMPOSITE`, `SUBSCRIPTION`, `PROFESSIONAL_SERVICE`, `PRO_SERVICE`.
- `billable_metric_id` (`string`, optional): Required for USAGE products. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `composite_product_ids` (`array`, optional): Required for COMPOSITE products. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `composite_scope` (`string`, optional): Determines what spend contributes to calculating this charge. When composite scope is contract, calculates composite charge based on applicable spend per contract. When composite scope is customer, calculates composite charge based on applicable spend across all customer contracts. Defaults to contract. Example: customer. One of: `customer`, `contract`.
- `composite_tags` (`array`, optional): Required for COMPOSITE products. Example: ["compute"]
- `custom_fields` (`object`, optional): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
- `exclude_free_usage` (`boolean`, optional): Beta feature only available for composite products. If true, products with $0 will not be included when computing composite usage. Defaults to false. Example: false
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `include_composite_spend` (`boolean`, optional): Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false. Example: false
- `is_refundable` (`boolean`, optional): This field's availability is dependent on your client's configuration. Defaults to true. Example: false
- `netsuite_internal_item_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `netsuite_overage_item_id` (`string`, optional): This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `presentation_group_key` (`array`, optional): For USAGE products only. Groups usage line items on invoices. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric. Example: ["region"]
- `pricing_group_key` (`array`, optional): For USAGE products only. If set, pricing for this product will be determined for each pricing_group_key value, as opposed to the product as a whole. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric. Example: ["region"]
- `quantity_conversion` (`object`, optional): Optional. Only valid for USAGE products. If provided, the quantity will be converted using the provided conversion factor and operation. For example, if the operation is "multiply" and the conversion factor is 100, then the quantity will be multiplied by 100. This can be used in cases where data is sent in one unit and priced in another. For example, data could be sent in MB and priced in GB. In this case, the conversion factor would be 1024 and the operation would be "divide". Example: {"conversion_factor": 100, "operation": "multiply"}
- `quantity_rounding` (`object`, optional): Optional. Only valid for USAGE products. If provided, the quantity will be rounded using the provided rounding method and decimal places. For example, if the method is "round up" and the decimal places is 0, then the quantity will be rounded up to the nearest integer. Example: {"rounding_method": "round_up", "decimal_places": 100}
- `sql_breakdown_granularity` (`string`, optional): Defines the breakdown behavior when calculating usage from SQL Billable Metrics. If set to 'service_period' (default), the usage will be evaluated once for all events the invoice service period and the usage will be applied at the last instant of the invoice. If set to 'hour', it will be broken down and evaluated for each hour. For most use cases, 'hour' is recommended. The setting has no effect for Streaming Billable Metrics. Example: HOUR. One of: `HOUR`, `SERVICE_PERIOD`.
- `tags` (`array`, optional): Tags on the product. Commits, credits, overrides and composite products can target products by tag. Example: ["compute", "api"]

Example input: `{"name":"<name>","type":"FIXED"}`

### `metronome_product_update`

Update Product · Write

Schedule changes to a product's name, billable metric, refundability, composite settings, tags, pricing and presentation group keys or quantity rules from a starting_at time on an hour boundary.
Returns data with the product id.
Use this to change a product without disrupting billing. Use metronome_product_archive to retire it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `product_id` (`string`, required): ID of the product to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `starting_at` (`string`, required): When the change takes effect, RFC 3339 on an hour boundary. Use a past time only if no invoices have been finalized since then. Example: 2026-02-01T00:00:00.000Z
- `billable_metric_id` (`string`, optional): Available for USAGE products only. If not provided, defaults to product's current billable metric. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `composite_product_ids` (`array`, optional): Available for COMPOSITE products only. If not provided, defaults to product's current composite_product_ids. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
- `composite_tags` (`array`, optional): Available for COMPOSITE products only. If not provided, defaults to product's current composite_tags. Example: ["compute"]
- `exclude_free_usage` (`boolean`, optional): Beta feature only available for composite products. If true, products with $0 will not be included when computing composite usage. Defaults to false. Example: false
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `include_composite_spend` (`boolean`, optional): Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false. Example: false
- `is_refundable` (`boolean`, optional): Defaults to product's current refundability status. This field's availability is dependent on your client's configuration. Example: false
- `name` (`string`, optional): displayed on invoices. If not provided, defaults to product's current name. Example: My Updated Product
- `netsuite_internal_item_id` (`string`, optional): If not provided, defaults to product's current netsuite_internal_item_id. This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `netsuite_overage_item_id` (`string`, optional): Available for USAGE and COMPOSITE products only. If not provided, defaults to product's current netsuite_overage_item_id. This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `presentation_group_key` (`array`, optional): For USAGE products only. Groups usage line items on invoices. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric. Example: ["region"]
- `pricing_group_key` (`array`, optional): For USAGE products only. If set, pricing for this product will be determined for each pricing_group_key value, as opposed to the product as a whole. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric. Example: ["region"]
- `quantity_conversion` (`object`, optional): Optional. Only valid for USAGE products. If provided, the quantity will be converted using the provided conversion factor and operation. For example, if the operation is "multiply" and the conversion factor is 100, then the quantity will be multiplied by 100. This can be used in cases where data is sent in one unit and priced in another. For example, data could be sent in MB and priced in GB. In this case, the conversion factor would be 1024 and the operation would be "divide". Example: {"conversion_factor": 100, "operation": "multiply"}
- `quantity_rounding` (`object`, optional): Optional. Only valid for USAGE products. If provided, the quantity will be rounded using the provided rounding method and decimal places. For example, if the method is "round up" and the decimal places is 0, then the quantity will be rounded up to the nearest integer. Example: {"rounding_method": "round_up", "decimal_places": 100}
- `sql_breakdown_granularity` (`string`, optional): Defines the breakdown behavior when calculating usage from SQL Billable Metrics. If set to 'service_period' (default), the usage will be evaluated once for all events the invoice service period and the usage will be applied at the last instant of the invoice. If set to 'hour', it will be broken down and evaluated for each hour. For most use cases, 'hour' is recommended. The setting has no effect for Streaming Billable Metrics. Example: HOUR. One of: `HOUR`, `SERVICE_PERIOD`.
- `tags` (`array`, optional): If not provided, defaults to product's current tags. Example: ["compute"]

Example input: `{"product_id":"<product_id>","starting_at":"<starting_at>"}`

### `metronome_rate_card_create`

Create Rate Card · Write

Create a rate card with a name, optional description, fiat pricing unit, custom pricing unit conversions and aliases.
Returns data with the new rate card id.
Use this to set up a new price list, then add prices with metronome_rate_card_rates_add.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Used only in UI/API. It is not exposed to end customers. Example: Standard pricing 2026
- `aliases` (`array`, optional): Reference this alias when creating a contract. If the same alias is assigned to multiple rate cards, it will reference the rate card to which it was most recently assigned. It is not exposed to end customers. Example: [{"name": "my-rate-card"}]
- `credit_type_conversions` (`array`, optional): Required when using custom pricing units in rates. Example: [{"custom_credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "fiat_per_custom_credit": 2}]
- `custom_fields` (`object`, optional): Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
- `description` (`string`, optional): Description of the rate card. Example: Standard 2026 list prices
- `fiat_credit_type_id` (`string`, optional): The Metronome ID of the credit type to associate with the rate card, defaults to USD (cents) if not passed. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>"}`

### `metronome_rate_card_products_move`

Move Rate Card Products · Write

Move specific products to new positions in a rate card's product order, which sets the order on invoices.
Returns data with the rate card id.
Use this to reorder a few products. Use metronome_rate_card_products_order_set to replace the whole order.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `product_moves` (`array`, required): Products to move. Each has a product_id and its new zero-based position. Example: [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "position": 0}]
- `rate_card_id` (`string`, required): ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"product_moves":[{"product_id":"2e30f074-d04c-412e-a134-851ebfa5ceb2","position":0}],"rate_card_id":"<rate_card_id>"}`

### `metronome_rate_card_products_order_set`

Set Rate Card Products Order · Write

Set the full order of products on a rate card, which is the order they appear on customers' invoices.
Returns data with the rate card id.
Use this to define the whole order at once. Use metronome_rate_card_products_move to move a few products.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `product_order` (`array`, required): Product IDs in the order they should appear on invoices. Example: ["2e30f074-d04c-412e-a134-851ebfa5ceb2", "1f4d2b6e-8c3a-4f5e-9a7b-2c1d0e9f8a7b"]
- `rate_card_id` (`string`, required): ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"product_order":["2e30f074-d04c-412e-a134-851ebfa5ceb2","1f4d2b6e-8c3a-4f5e-9a7b-2c1d0e9f8a7b"],"rate_card_id":"<rate_card_id>"}`

### `metronome_rate_card_rate_add`

Add Rate to Rate Card · Write

Add one rate for a product to a rate card from a start date: flat, percentage, subscription, tiered or custom, with optional pricing group values and billing frequency.
Returns data with the created rate (rate_type, price, tiers, quantity, pricing_group_values, credit_type and commit_rate).
Use this for a single rate. Metronome rate-limits it heavily, so use metronome_rate_card_rates_add for more than one rate.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `entitled` (`boolean`, required): Whether customers on this rate card can use the product at this rate. Set false to list a product that is not available by default. Example: true
- `product_id` (`string`, required): ID of the product to add a rate for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `rate_card_id` (`string`, required): ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `rate_type` (`string`, required): How the price is applied: FLAT (price per unit), PERCENTAGE (a fraction of other spend), SUBSCRIPTION (price per unit per billing period, with quantity), TIERED (tiers) or CUSTOM (custom_rate). Example: FLAT. One of: `FLAT`, `PERCENTAGE`, `SUBSCRIPTION`, `TIERED`, `TIERED_PERCENTAGE`, `CUSTOM`.
- `starting_at` (`string`, required): inclusive effective date. Example: 2026-01-01T00:00:00.000Z
- `billing_frequency` (`string`, optional): Optional. Frequency to bill subscriptions with. Required for subscription type products with Flat rate. Example: MONTHLY. One of: `MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, `ANNUAL`, `WEEKLY`.
- `commit_rate` (`object`, optional): A distinct rate on the rate card. You can choose to use this rate rather than list rate when consuming a credit or commit. Example: {"rate_type": "FLAT"}
- `credit_type_id` (`string`, optional): The Metronome ID of the credit type to associate with price, defaults to USD (cents) if not passed. Used by all rate_types except type PERCENTAGE. PERCENTAGE rates use the credit type of associated rates. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
- `custom_rate` (`object`, optional): Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. Example: {"rate_key": "premium"}
- `ending_before` (`string`, optional): exclusive end date. Example: 2026-02-01T00:00:00.000Z
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `is_prorated` (`boolean`, optional): Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. Example: false
- `minimum_config` (`object`, optional): Only set for TIERED_PERCENTAGE or PERCENTAGE rate_type. Any commit-specific overrides will not apply if there is a minimum set on the rate/applied override. Example: {"minimum": 100}
- `price` (`number`, optional): Default price. For FLAT and SUBSCRIPTION rate_type, this must be >=0. For PERCENTAGE rate_type, this is a decimal fraction, e.g. use 0.1 for 10%; this must be >=0 and <=1. Example: 0.5
- `pricing_group_values` (`object`, optional): Optional. List of pricing group key value pairs which will be used to calculate the price. Example: {"key": "value"}
- `quantity` (`number`, optional): Default quantity. For SUBSCRIPTION rate_type, this must be >=0. Example: 100
- `tiers` (`array`, optional): Only set for TIERED rate_type. Example: [{"price": 100}]

Example input: `{"entitled":true,"product_id":"<product_id>","rate_card_id":"<rate_card_id>","rate_type":"FLAT","starting_at":"<starting_at>"}`

### `metronome_rate_card_rates_add`

Add Rates to Rate Card · Write

Add several rates to a rate card in one call. Each rate has its product, start date, rate type and price or tiers.
Returns data with the rate card id.
Use this to load prices in bulk. Use metronome_rate_card_rate_add for a single rate.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `rate_card_id` (`string`, required): Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `rates` (`array`, required): Rates to add. Each needs a product_id, starting_at (RFC 3339, hour boundary), entitled (true or false) and rate_type (FLAT, PERCENTAGE, SUBSCRIPTION, TIERED or CUSTOM), plus price for FLAT, PERCENTAGE and SUBSCRIPTION or tiers for TIERED. Optional: ending_before, pricing_group_values, billing_frequency, credit_type_id, quantity and is_prorated. Example: [{"product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2", "starting_at": "2026-01-01T00:00:00.000Z", "entitled": true, "rate_type": "FLAT", "price": 0.5}]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"rate_card_id":"<rate_card_id>","rates":[{"product_id":"2e30f074-d04c-412e-a134-851ebfa5ceb2","starting_at":"2026-01-01T00:00:00.000Z","entitled":true,"rate_type":"FLAT","price":0.5}]}`

### `metronome_rate_card_update`

Update Rate Card · Write

Update a rate card's name, description or aliases, or add credit type conversions. Prices are not changed.
Returns data with the rate card id.
Use this to rename or re-alias a rate card. Use metronome_rate_card_rate_add or metronome_rate_card_rates_add to change prices.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `rate_card_id` (`string`, required): ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `add_credit_type_conversions` (`array`, optional): Add credit type conversions for using custom pricing units in rates. Existing conversions cannot be modified. Example: [{"custom_credit_type_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "fiat_per_custom_credit": 100}]
- `aliases` (`array`, optional): Reference this alias when creating a contract. If the same alias is assigned to multiple rate cards, it will reference the rate card to which it was most recently assigned. It is not exposed to end customers. Example: [{"name": "standard-2026"}]
- `description` (`string`, optional): New description for the rate card. Example: Standard 2026 list prices
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): Used only in UI/API. It is not exposed to end customers. Example: My Updated Rate Card

Example input: `{"rate_card_id":"<rate_card_id>"}`

### `metronome_threshold_commit_release`

Release Threshold Billing Commit · Write

Report the outcome of an external payment attempt for a threshold billing commit, which releases the pending commit when paid or cancels it when failed.
Returns an empty response on success.
Use this only with threshold billing through your own payment gateway, after you have charged the customer.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `outcome` (`string`, required): The outcome of the external payment gate. Example: paid. One of: `paid`, `failed`.
- `workflow_id` (`string`, required): ID of the workflow to continue. Example: 5576ba1f-4a33-b473-3f05-6162d87b4a33
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"outcome":"paid","workflow_id":"<workflow_id>"}`

### `metronome_alert_archive`

Archive Threshold Notification · Destructive

Archive a threshold notification so it stops being evaluated for all customers, optionally releasing its uniqueness key.
Returns data with the archived alert id.
Use this to retire an alert. Use metronome_customer_alert_reset to only re-evaluate it.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): The Metronome ID of the threshold notification. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `release_uniqueness_key` (`boolean`, optional): If true, resets the uniqueness key on this threshold notification so it can be re-used. Example: false

Example input: `{"id":"<id>"}`

### `metronome_billable_metric_archive`

Archive Billable Metric · Destructive

Archive a billable metric so it cannot be used by new products. Products that already use it keep working.
Returns data with the archived billable metric id.
Use this to retire a metric that is no longer used.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ID of the billable metric to archive. Get it from metronome_billable_metrics_list. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `metronome_commit_archive`

Archive Commit · Destructive

Archive a contract-level or customer-level commit, keeping its history. All finalized invoices it was applied to, and its own payment invoices, must be voided first.
Returns data with the archived commit id.
Use this to remove a commit created in error. Use metronome_commit_end_date_update to end a valid commit early.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `commit_id` (`string`, required): ID of the commit to archive. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
- `customer_id` (`string`, required): ID of the customer whose commit is being archived. Example: 4c91c473-fc12-445a-9c38-40421d47023f
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"commit_id":"<commit_id>","customer_id":"<customer_id>"}`

### `metronome_contract_archive`

Archive Contract · Destructive

Archive a contract and all its terms. Draft invoices are canceled, upcoming scheduled invoices are voided, and finalized invoices can also be voided.
Returns data with the archived contract id.
Use this for a contract created by mistake. It cannot be undone. Use metronome_contract_end_date_update to end a valid contract early instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `contract_id` (`string`, required): ID of the contract to archive. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `customer_id` (`string`, required): ID of the customer whose contract is to be archived. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
- `void_invoices` (`boolean`, required): If false, the existing finalized invoices will remain after the contract is archived. Example: true
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"contract_id":"<contract_id>","customer_id":"<customer_id>","void_invoices":true}`

### `metronome_credit_archive`

Archive Credit · Destructive

Archive a contract-level or customer-level credit, keeping its history. All finalized invoices it was applied to must be voided first.
Returns data with the archived credit id.
Use this to remove a credit created in error. Use metronome_credit_end_date_update to end a valid credit early.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `credit_id` (`string`, required): ID of the credit to archive. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
- `customer_id` (`string`, required): ID of the customer whose credit is being archived. Example: 4c91c473-fc12-445a-9c38-40421d47023f
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"credit_id":"<credit_id>","customer_id":"<customer_id>"}`

### `metronome_custom_field_key_delete`

Delete Custom Field Key · Destructive

Remove a custom field key from an entity type. Existing values for the key are no longer accessible.
Returns an empty response on success.
Use this to retire a custom field everywhere. Use metronome_custom_field_values_delete to remove values from one entity.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `entity` (`string`, required): Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customer. One of: `alert`, `billable_metric`, `charge`, `commit`, `contract_credit`, `contract_product`, `contract`, `customer`, `discount`, `invoice`, `professional_service`, `product`, `rate_card`, `scheduled_charge`, `subscription`, `package_commit`, `package_credit`, `package_subscription`, `package_scheduled_charge`.
- `key` (`string`, required): Name of the custom field key to remove. Example: region
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"entity":"alert","key":"<key>"}`

### `metronome_custom_field_values_delete`

Delete Custom Field Values · Destructive

Remove some custom field values from one entity, keeping its other fields.
Returns an empty response on success.
Use this to clear values on one entity. Use metronome_custom_field_key_delete to retire a key everywhere.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `entity` (`string`, required): Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customer. One of: `alert`, `billable_metric`, `charge`, `commit`, `contract_credit`, `contract_product`, `contract`, `customer`, `discount`, `invoice`, `professional_service`, `product`, `rate_card`, `scheduled_charge`, `subscription`, `package_commit`, `package_credit`, `package_subscription`, `package_scheduled_charge`.
- `entity_id` (`string`, required): ID of the object (for example the customer ID or contract ID) whose custom field values you are changing. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `keys` (`array`, required): Custom field keys whose values to remove from the object. Example: ["region"]
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"entity":"alert","entity_id":"<entity_id>","keys":["region"]}`

### `metronome_customer_archive`

Archive Customer · Destructive

Archive a customer. Metronome also archives all of the customer's contracts as of now and voids their invoices.
Returns data with the archived customer's id.
Use this only for a customer onboarded by mistake or fully churned. It cannot be undone. Use metronome_contract_archive to remove just one contract.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Metronome customer ID (a UUID) of the customer to archive. Archiving also archives the customer's contracts and voids their invoices. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `metronome_customer_billing_configs_archive`

Archive Customer Billing Configurations · Destructive

Archive billing provider configurations for a customer. It takes effect immediately, and contracts that use the configuration stop sending invoices downstream.
Returns data with the archived configuration IDs and the customer_id.
Use this when a customer churns from a billing provider or changes how they pay. Get configuration IDs from metronome_customer_billing_configs_get.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `customer_billing_provider_configuration_ids` (`array`, required): Array of billing provider configuration IDs to archive. Example: ["4db51251-61de-4bfe-b9ce-495e244f3491", "4db51251-61de-4bfe-b9ce-495e244f3491"]
- `customer_id` (`string`, required): The customer ID the billing provider configurations belong to. Example: 20a060d1-aa80-41d4-8bb2-4f3091b93903
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"customer_billing_provider_configuration_ids":["4db51251-61de-4bfe-b9ce-495e244f3491","4db51251-61de-4bfe-b9ce-495e244f3491"],"customer_id":"<customer_id>"}`

### `metronome_invoice_void`

Void Invoice · Destructive

Void an invoice so it is not collected and is removed from the customer's billing.
Returns data with the voided invoice id.
Use this to cancel an incorrect or disputed invoice. Use metronome_invoice_regenerate afterwards to recalculate it.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): The invoice id to void. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `metronome_notification_archive`

Archive Offset Notification · Destructive

Archive an offset lifecycle event notification so it is no longer processed.
Returns data with the archived notification.
Use this to remove a custom notification.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): The ID of the offset lifecycle event notification configuration to archive. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `metronome_package_archive`

Archive Package · Destructive

Archive a package so it can no longer be used for new contracts. Existing contracts on it keep working.
Returns data with the archived package id.
Use this to retire a package. It cannot be unarchived.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `package_id` (`string`, required): ID of the package to archive. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"package_id":"<package_id>"}`

### `metronome_pricing_unit_archive`

Archive Pricing Unit · Destructive

Archive a custom pricing unit so it no longer appears in pricing unit selectors by default.
Returns data with the archived pricing unit id.
Use this to retire a custom unit.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ID of the custom pricing unit to archive. Get it from metronome_pricing_units_list. Example: fa2f1b3d-9d52-4951-a099-25991fd394d6
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `metronome_product_archive`

Archive Product · Destructive

Archive a product so it can no longer be used for new rates. Existing rate cards that use it keep working.
Returns data with the archived product id.
Use this to retire a product. It cannot be unarchived.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `product_id` (`string`, required): ID of the product to be archived. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"product_id":"<product_id>"}`

### `metronome_rate_card_archive`

Archive Rate Card · Destructive

Archive a rate card so it can no longer be used for new contracts. Existing contract pricing is kept.
Returns data with the archived rate card id.
Use this to retire an old price list. It cannot be unarchived.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ID of the rate card to archive. Get it from metronome_rate_cards_list. Example: 12b21470-4570-40df-8998-449d0b0bc52f
- `idempotency_key` (`string`, optional): Optional Idempotency-Key header value, unique per request. If the call times out or fails mid-way, retry with the same key and identical inputs to get the original result instead of applying the change twice. Reusing a key with different inputs returns 409 Conflict. Metronome keeps keys for at least 24 hours. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

## Related

Other Accounting & Finance connectors ([all 82](/agentkit/connectors/?category=accounting-finance)):

- [QuickBooks](/agentkit/connectors/quickbooks/): Scalekit connector, OAuth, 117 tools
- [Xero](/agentkit/connectors/xero/): Scalekit connector, OAuth, 94 tools
- [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
