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.
- Tools
- 104
- What they doRead · write · destructive
- 45 · 44 · 1545 read44 write15 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Metronome connection
In AgentKit > Connections, create a Metronome connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts 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.actionsconst connector = 'metronome'const identifier = 'user_123'// Generate an authorization link for the userconst { 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 callconst result = await actions.executeTool({connector,identifier,toolName: 'metronome_audit_logs_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_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.actionsconnection_name = "metronome"identifier = "user_123"# Generate an authorization link for the userlink_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 callresult = actions.execute_tool(tool_input={},tool_name="metronome_audit_logs_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Metronome credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolmetronome_audit_logs_listList 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.Read-onlyList Audit Logs
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.
Inputs
ending_beforestring- RFC 3339 timestamp (exclusive). Cannot be used with 'next_page'. Example: 2026-02-01T00:00:00.000Z
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
resource_idstring- 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_typestring- 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
sortstring- Sort order by timestamp, e.g. date_asc or date_desc. Defaults to date_asc. Example: date_ascone of
date_ascdate_desc starting_onstring- RFC 3339 timestamp of the earliest audit log to return. Cannot be used with 'next_page'. Example: 2026-01-01T00:00:00.000Z
metronome_balances_listList a customer's balances: commits and credits, customer-level and optionally contract-level, with optional date filters, archived items, ledgers and current balance.Read-onlyList Customer Balances
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
access_typestring- Filters balances by how they are drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used. Example: SPENDone of
SPENDQUANTITY covering_datestring- Return only balances that have access schedules that "cover" the provided date. Example: 2026-01-15T00:00:00.000Z
effective_beforestring- Include only balances that have any access before the provided date (exclusive) Example: 2026-02-01T00:00:00.000Z
exclude_zero_balancesboolean- Exclude balances with zero amounts from the response. Example: false
idstring- Return only the commit or credit with this ID. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
include_archivedboolean- Include archived credits and credits from archived contracts. Example: false
include_balanceboolean- Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. Example: false
include_contract_balancesboolean- Include balances on the contract level. Example: false
include_ledgersboolean- Include ledgers in the response. Setting this flag may cause the query to be slower. Example: true
limitinteger- The maximum number of commits to return. Defaults to 25. Example: 25
next_pagestring- The next page token from a previous response. Example: 0c34b75b47491b73db66d46737d9a87
starting_atstring- Include only balances that have any access on or after the provided date. Example: 2026-01-01T00:00:00.000Z
webhook_notification_idstring- Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_billable_metric_getGet one billable metric's full configuration.Read-onlyGet Billable Metric
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.
Inputs
billable_metric_idstringrequired- Billable metric ID (a UUID). Get it from metronome_billable_metrics_list. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
metronome_billable_metrics_listList billable metrics (how usage events are filtered and aggregated) with their full configuration, optionally including archived ones.Read-onlyList Billable Metrics
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.
Inputs
include_archivedboolean- If true, the list of returned metrics will include archived metrics. Example: false
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_billing_providers_listList the billing providers configured for the account and their delivery methods.Read-onlyList Billing Providers
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.
Inputs
next_pagestring- The cursor to the next page of results. Example: af26878a-de62-4a0d-9b77-3936f7c2b6d6
metronome_commits_listList a customer's prepaid and postpaid commits, optionally one commit, contract-level commits, archived commits, ledgers and balances.Read-onlyList Commits
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
access_typestring- Filters commits by how their balances are drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used. Example: SPENDone of
SPENDQUANTITY commit_idstring- Commit ID (a UUID). Get it from metronome_commits_list or metronome_balances_list. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
covering_datestring- Include only commits that have access schedules that "cover" the provided date. Example: 2026-01-15T00:00:00.000Z
effective_beforestring- Include only commits that have any access before the provided date (exclusive) Example: 2026-02-01T00:00:00.000Z
include_archivedboolean- Include archived commits and commits from archived contracts. Example: false
include_balanceboolean- Include the balance in the response. Setting this flag may cause the query to be slower. Example: false
include_contract_commitsboolean- Include commits on the contract level. Example: false
include_ledgersboolean- Include commit ledgers in the response. Setting this flag may cause the query to be slower. Example: true
limitinteger- The maximum number of commits to return. Defaults to 25. Example: 25
next_pagestring- The next page token from a previous response. Example: 0c34b75b47491b73db66d46737d9a87
starting_atstring- Include only commits that have any access on or after the provided date. Example: 2026-01-01T00:00:00.000Z
metronome_contract_edit_history_getList every edit made to a contract since it was created, whether through the app, the edit endpoint or other update endpoints.Read-onlyGet Contract Edit History
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.
Inputs
contract_idstringrequired- Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
metronome_contract_getGet one contract with its full terms: rate card, commits, credits, overrides, discounts, scheduled charges, subscriptions and billing configuration, optionally as of a past date.Read-onlyGet Contract
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.
Inputs
contract_idstringrequired- Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
as_of_datestring- 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_balanceboolean- Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. Example: false
include_ledgersboolean- 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_idstring- Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_contract_rate_schedule_getGet 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.Read-onlyGet Contract Rate Schedule
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.
Inputs
contract_idstringrequired- ID of the contract to get the rate schedule for. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- ID of the customer for whose contract to get the rate schedule for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
atstring- 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
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
selectorsarray- 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"}}]
metronome_contracts_listList 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.Read-onlyList Customer Contracts
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
covering_datestring- 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
cursorstring- Cursor from a previous response to fetch the next page of contracts. Example: 0c34b75b47491b73db66d46737d9a87
include_archivedboolean- Include archived contracts in the response. Example: false
include_balanceboolean- Include the balance of credits and commits in the response. Setting this flag may cause the response to be slower. Example: false
include_ledgersboolean- Include commit/credit ledgers in the response. Setting this flag may cause the response to be slower. Example: false
limitnumber- Max number of contracts to return per page. Range: 1-20. Default: 20. Example: 25
starting_atstring- 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
metronome_credits_listList a customer's credits, optionally one credit, contract-level credits, archived credits, ledgers and balances.Read-onlyList Credits
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
covering_datestring- Return only credits that have access schedules that "cover" the provided date. Example: 2026-01-15T00:00:00.000Z
credit_idstring- Credit ID (a UUID). Get it from metronome_credits_list or metronome_balances_list. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
effective_beforestring- Include only credits that have any access before the provided date (exclusive) Example: 2026-02-01T00:00:00.000Z
include_archivedboolean- Include archived credits and credits from archived contracts. Example: false
include_balanceboolean- Include the balance in the response. Setting this flag may cause the query to be slower. Example: false
include_contract_creditsboolean- Include credits on the contract level. Example: false
include_ledgersboolean- Include credit ledgers in the response. Setting this flag may cause the query to be slower. Example: true
limitinteger- The maximum number of commits to return. Defaults to 25. Example: 25
next_pagestring- The next page token from a previous response. Example: 0c34b75b47491b73db66d46737d9a87
starting_atstring- Include only credits that have any access on or after the provided date. Example: 2026-01-01T00:00:00.000Z
metronome_custom_field_keys_listList the active custom field keys, optionally only for some entity types (customer, contract, product, commit and others).Read-onlyList Custom Field Keys
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.
Inputs
entitiesarray- Optional list of entity types to return keys for. Example: ["customer"]
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_customer_alert_getGet the current evaluation status of one threshold notification for one customer.Read-onlyGet Customer Threshold Notification
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.
Inputs
alert_idstringrequired- The Metronome ID of the threshold notification. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
customer_idstringrequired- The Metronome ID of the customer. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
alert_specifiersarray- 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_filtersarray- Used to filter the alert by the custom field key-value pair. Example: [{"entity": "Contract", "key": "region", "value": "emea"}]
group_valuesarray- 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_contractsstring- When parallel threshold notifications are enabled during migration, this flag denotes whether to fetch notifications for plans or contracts. Example: PLANSone of
PLANSCONTRACTS seat_filterobject- 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_idstring- Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_customer_alerts_listList the threshold notifications that apply to a customer with their current status, optionally filtered by alert status.Read-onlyList Customer Threshold Notifications
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.
Inputs
customer_idstringrequired- The Metronome ID of the customer. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
alert_statusesarray- Optionally filter by threshold notification status. If absent, only enabled notifications will be returned. Example: ["enabled"]
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_customer_billable_metrics_listList the billable metrics available for one customer, optionally only those on the customer's current contract or plan, and optionally including archived ones.Read-onlyList Customer Billable Metrics
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
include_archivedboolean- If true, the list of returned metrics will include archived metrics. Example: false
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
on_current_planboolean- If true, the list of metrics will be filtered to just ones that are on the customer's current plan. Example: false
metronome_customer_billing_configs_getGet the billing provider configurations set up for a customer, such as Stripe, AWS Marketplace or NetSuite delivery settings.Read-onlyGet Customer Billing Configurations
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
include_archivedboolean- Set to true to also return archived billing provider configurations. Defaults to false. Example: false
metronome_customer_events_previewPreview how a set of usage events would change a customer's draft invoices under their current contracts, without ingesting the events.Read-onlyPreview Events on Invoices
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
eventsarrayrequired- 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_keystring- 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
modestring- 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: replaceone of
replacemerge skip_zero_qty_line_itemsboolean- When `true`, line items with zero quantity are excluded from the response. Example: false
metronome_customer_getGet one Metronome customer by its Metronome customer ID.Read-onlyGet Customer
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_customers_listList customers in the Metronome account, optionally filtered by ingest alias, customer IDs, Salesforce account IDs, Stripe customer ID or archived status.Read-onlyList Customers
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.
Inputs
customer_idsarray- Filter the customer list by customer_id. Up to 100 ids can be provided. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
ingest_aliasstring- Filter the customer list by ingest_alias. Example: team@example.com
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
only_archivedboolean- Filter the customer list to only return archived customers. By default, only active customers are returned. Example: false
salesforce_account_idsarray- Filter the customer list by salesforce_account_id. Up to 100 ids can be provided. Example: ["0015000000XyZAB"]
stripe_customer_idstring- 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
metronome_events_searchLook up usage events from the last 34 days by transaction ID.Read-onlySearch Usage Events
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.
Inputs
transactionIdsarrayrequired- The transaction IDs of the events to retrieve. Example: ["sktest-txn-0001"]
metronome_invoice_breakdowns_listBreak 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.Read-onlyList Invoice Breakdowns
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
ending_beforestringrequired- 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_onstringrequired- 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_idstring- Only return invoices for the specified credit type. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
limitinteger- 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_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
skip_zero_qty_line_itemsboolean- If set, all zero quantity line items will be filtered out of the response. Example: false
sortstring- Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. Example: date_ascone of
date_ascdate_desc statusstring- Invoice status, e.g. DRAFT or FINALIZED. Example: FINALIZED
window_sizestring- The granularity of the breakdowns to return. Defaults to day. Example: dayone of
hourday
metronome_invoice_getGet one invoice of a customer with its line items, applied credits, totals and billing period, draft or finalized.Read-onlyGet Invoice
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
invoice_idstringrequired- Invoice ID (a UUID). Get it from metronome_invoices_list. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
skip_zero_qty_line_itemsboolean- If set, all zero quantity line items will be filtered out of the response. Example: false
metronome_invoices_listList a customer's invoices, optionally filtered by status, type, contract, pricing unit or date range, and sorted by date.Read-onlyList Invoices
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
contract_idstring- Only return invoices for the specified contract. Example: 9b85c1c1-5238-4f2a-a409-61412905e1e1
credit_type_idstring- Only return invoices for the specified credit type. Example: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
ending_beforestring- 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_invoicesboolean- When true, includes historical commit invoices alongside active invoices. Defaults to false. Example: false
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
skip_zero_qty_line_itemsboolean- If set, all zero quantity line items will be filtered out of the response. Example: false
sortstring- Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. Example: date_ascone of
date_ascdate_desc starting_onstring- 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
statusstring- Invoice status, e.g. DRAFT, FINALIZED, or VOID. Example: FINALIZED
typestring- Filter invoices by type. Defaults to returning all invoice types. Example: USAGEone of
USAGEUSAGE_CONSOLIDATEDSCHEDULED webhook_notification_idstring- Indicates that this API request was triggered by a webhook notification with the provided ID. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_net_balance_getGet a customer's combined current balance across their credits and commits, optionally for one pricing unit, access type, or filtered set of balances.Read-onlyGet Customer Net Balance
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.
Inputs
customer_idstringrequired- The ID of the customer. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
access_typestring- Filters balances by how they are drawn down. Defaults to `SPEND`. If set to `QUANTITY`, `credit_type_id` must not be provided. Example: SPENDone of
SPENDQUANTITY credit_type_idstring- 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
filtersarray- 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_modestring- 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_DRAFTone of
FINALIZEDFINALIZED_AND_DRAFT
metronome_notification_getGet one offset lifecycle event notification by ID.Read-onlyGet Offset Notification
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.
Inputs
idstringrequired- The ID of the notification configuration to retrieve. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_offset_notifications_listList offset lifecycle event notifications, which fire at a set time before or after events such as a contract or commit starting or ending.Read-onlyList Offset Notifications
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.
Inputs
archive_filterstring- Filter options for the notification configurations. If not provided, defaults to NOT_ARCHIVED. Example: NOT_ARCHIVEDone of
ARCHIVEDNOT_ARCHIVEDALL cursorstring- 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
limitnumber- Maximum number of notifications to return (up to 400). Example: 50
metronome_package_contracts_listList the contracts and customers that use a package, optionally only those active on a date or starting after a date.Read-onlyList Contracts on Package
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.
Inputs
package_idstringrequired- Package ID (a UUID). Get it from metronome_packages_list. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
covering_datestring- 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_archivedboolean- Default false. Determines whether to include archived contracts in the results. Example: false
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
starting_atstring- 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
metronome_package_getGet one package with its name, aliases, duration and contract terms.Read-onlyGet Package
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.
Inputs
package_idstringrequired- Package ID (a UUID). Get it from metronome_packages_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
metronome_packages_listList contract packages (reusable contract templates), optionally including archived ones.Read-onlyList Packages
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.
Inputs
archive_filterstring- Filter packages by archived status. Defaults to NOT_ARCHIVED. Example: ARCHIVEDone of
ARCHIVEDNOT_ARCHIVEDALL limitinteger- The maximum number of packages to return. Defaults to 10. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_pricing_units_listList pricing units (credit types): fiat currencies such as USD and any custom units such as AI credits.Read-onlyList Pricing Units
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.
Inputs
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_product_getGet one product with its current configuration and the history of scheduled changes.Read-onlyGet Product
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.
Inputs
idstringrequired- Product ID (a UUID). Get it from metronome_products_list. Example: d84e7f4e-7a70-4fe4-be02-7a5027beffcc
metronome_products_listList products (the line items you bill for), with archived products excluded unless requested.Read-onlyList Products
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.
Inputs
archive_filterstring- Filter options for the product list. If not provided, defaults to not archived. Example: NOT_ARCHIVEDone of
ARCHIVEDNOT_ARCHIVEDALL limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_rate_card_getGet one rate card's name, description, pricing unit, credit type conversions, aliases and custom fields.Read-onlyGet Rate Card
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.
Inputs
idstringrequired- Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: f3d51ae8-f283-44e1-9933-a3cf9ad7a6fe
metronome_rate_card_rates_getGet the rates on a rate card at one point in time, optionally filtered by product, product tags or pricing group values.Read-onlyGet Rate Card Rates
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.
Inputs
atstringrequired- inclusive starting point for the rates schedule. Example: 2024-01-01T00:00:00.000Z
rate_card_idstringrequired- ID of the rate card to get the schedule for. Example: f3d51ae8-f283-44e1-9933-a3cf9ad7a6fe
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
selectorsarray- 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"}}]
metronome_rate_card_schedule_getGet 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.Read-onlyGet Rate Card Schedule
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.
Inputs
rate_card_idstringrequired- ID of the rate card to get the schedule for. Example: f3d51ae8-f283-44e1-9933-a3cf9ad7a6fe
starting_atstringrequired- inclusive starting point for the rates schedule. Example: 2024-01-01T00:00:00.000Z
ending_beforestring- 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
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
selectorsarray- 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"}}]
metronome_rate_cards_listList rate cards (the price lists contracts are based on).Read-onlyList Rate Cards
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.
Inputs
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_seat_balances_listList 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.Read-onlyList Seat Balances
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.
Inputs
contract_idstringrequired- The contract ID to retrieve seat balances for. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- The customer ID to retrieve seat balances for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
covering_datestring- 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
cursorstring- Page token from a previous response to retrieve the next page. Example: 0c34b75b47491b73db66d46737d9a87
effective_beforestring- 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_commitsboolean- Include credits and commits in the response. Example: true
include_ledgersboolean- 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
limitinteger- 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_idsarray- Optional filter to only include specific seats. Example: ["seat-alice"]
skip_missing_seat_idsboolean- 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_atstring- 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_idsarray- 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"]
metronome_services_listList Metronome's services and their IP addresses for firewall allowlisting.Read-onlyList Services
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.
Inputs
This tool takes no inputs.
metronome_subscription_quantity_history_getGet the past changes in quantity and price for one subscription on a contract.Read-onlyGet Subscription Quantity History
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.
Inputs
contract_idstringrequired- Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
subscription_idstringrequired- ID of a subscription on the contract. Get it from the subscriptions array of metronome_contract_get. Example: 1a824d53-bde6-4d82-96d7-6347ff227d5c
metronome_subscription_seats_history_getGet the seat schedule for one seat-based subscription on a contract over time, optionally for one date or a date range.Read-onlyGet Subscription Seats History
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.
Inputs
contract_idstringrequired- Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
subscription_idstringrequired- ID of a subscription on the contract. Get it from the subscriptions array of metronome_contract_get. Example: 1a824d53-bde6-4d82-96d7-6347ff227d5c
covering_datestring- 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
cursorstring- 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_beforestring- 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
limitinteger- Maximum number of seat schedule entries to return. Defaults to 10. Required range: 1 <= x <= 10. Example: 10
starting_atstring- 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
metronome_system_notifications_listList Metronome's built-in system notification types and whether each is enabled.Read-onlyList System Notification Types
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.
Inputs
This tool takes no inputs.
metronome_usage_getGet aggregated usage for many customers and billable metrics over a date range, in hourly, daily or whole-range windows.Read-onlyGet Usage
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.
Inputs
ending_beforestringrequired- Must be aligned to UTC midnight and at least one day after `starting_on`. Example: 2026-01-08T00:00:00.000Z
starting_onstringrequired- Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`. Example: 2026-01-01T00:00:00.000Z
window_sizestringrequired- 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: dayone of
hourdaynone billable_metricsarray- 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_idsarray- 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_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
metronome_usage_grouped_listGet 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.Read-onlyList Grouped Usage
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.
Inputs
billable_metric_idstringrequired- Billable metric ID (a UUID). Get it from metronome_billable_metrics_list. Example: 222796fd-d29c-429e-89b2-549fabda4ed6
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 04ca7e72-4229-4a6e-ab11-9f7376fccbcb
window_sizestringrequired- 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: dayone of
hourdaynone ending_beforestring- Must be aligned to UTC midnight and at least one day after `starting_on`. Example: 2026-01-08T00:00:00.000Z
group_byobject- 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_filtersobject- 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_keyarray- 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"]
limitinteger- Max number of results that should be returned. Example: 25
next_pagestring- Cursor that indicates where the next page of results should start. Example: 0c34b75b47491b73db66d46737d9a87
starting_onstring- Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`. Example: 2026-01-01T00:00:00.000Z
metronome_webhook_deliveries_listList notifications sent to a webhook destination in the last 30 days, with their delivery attempts, optionally filtered by date, customer, notification type or status.Read-onlyList Webhook Deliveries
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.
Inputs
start_datestringrequired- 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_idstringrequired- 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_datestring- 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
filtersobject- 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"]}
limitnumber- Maximum number of notifications per page. Defaults to 25; must be an integer from 1 to 100. Example: 25
next_pagestring- 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
metronome_webhook_delivery_getGet one triggered notification sent to a webhook destination, with its payload and every delivery attempt.Read-onlyGet Webhook Delivery
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.
Inputs
triggered_notification_idstringrequired- ID of the triggered notification. Example: 4f98dc25-6be7-4b0c-b25b-946c19511c5d
webhook_idstringrequired- ID of the webhook destination. Only notifications from the same Metronome environment as your API token are returned. Example: eb3a41d4-ca42-4cc1-b184-d208ab56ed65
metronome_alert_createCreate 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.WriteCreate Threshold Notification
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.
Inputs
alert_typestringrequired- Type of the threshold notification. Example: low_remaining_contract_credit_and_commit_balance_reachedone of
spend_threshold_reachedmonthly_invoice_total_spend_threshold_reachedusage_threshold_reachedlow_remaining_days_for_commit_segment_reachedlow_remaining_commit_balance_reachedlow_remaining_commit_percentage_reachedlow_remaining_days_for_contract_credit_segment_reachedlow_remaining_contract_credit_balance_reachedlow_remaining_contract_credit_percentage_reachedlow_remaining_contract_credit_and_commit_balance_reachedlow_remaining_contract_credit_and_commit_percentage_reachedinvoice_total_reachedlow_remaining_seat_balance_reached namestringrequired- Name of the threshold notification. Example: Low balance warning
thresholdnumberrequired- 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_typestring- 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: SPENDone of
SPENDQUANTITY alert_specifiersarray- 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_idstring- 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_filtersarray- 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_idstring- 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_filtersarray- 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_idstring- 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_createboolean- 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_valuesarray- 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_filterarray- Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate. Example: ["SCHEDULED or USAGE"]
seat_filterobject- 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_keystring- 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
metronome_anrok_token_upsertSet the Anrok tax API token for billing provider delivery methods.WriteUpsert Anrok API Token
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.
Inputs
anrok_api_tokenstringrequired- The Anrok API token that is added to the configuration. Example: s123/sak456/secret.789
delivery_method_idsarrayrequired- 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_keystring- 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
metronome_avalara_credentials_upsertSet the Avalara tax credentials (environment, username, password) for billing provider delivery methods.WriteUpsert Avalara Credentials
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.
Inputs
avalara_environmentstringrequired- The Avalara environment to use (SANDBOX or PRODUCTION). Example: PRODUCTIONone of
PRODUCTIONSANDBOX avalara_passwordstringrequired- Avalara account password, sent to Metronome in the request body. Treat tool inputs that carry it as sensitive. Example: my_password_123
avalara_usernamestringrequired- The username for the Avalara account. Example: test@metronome.com
delivery_method_idsarrayrequired- 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_transactionsboolean- Commit transactions if you want Metronome tax calculations used for reporting and tax filings. Example: true
idempotency_keystring- 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
metronome_balance_ledger_entry_createAdd a manual ledger entry to a commit or credit segment to raise or lower its available balance, with a reason.WriteAdd Manual Balance Entry
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.
Inputs
amountnumberrequired- Amount to add to the segment. A negative number will draw down from the balance. Example: -1000
customer_idstringrequired- ID of the customer whose balance is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
idstringrequired- ID of the balance (commit or credit) to update. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
reasonstringrequired- Reason for the manual adjustment. This will be displayed in the ledger. Example: Reason for entry
segment_idstringrequired- ID of the segment to update. Example: 66368e29-3f97-4d15-a6e9-120897f0070a
contract_idstring- ID of the contract to update. Leave blank to update a customer level balance. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
per_group_amountsobject- 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}
timestampstring- 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_keystring- 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
metronome_billable_metric_createCreate 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.WriteCreate Billable Metric
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.
Inputs
namestringrequired- The display name of the billable metric. Example: API requests
aggregation_keystring- Specifies the type of aggregation performed on matching events. Required if `sql` is not provided. Example: cpu_hours
aggregation_typestring- Specifies the type of aggregation performed on matching events. Example: countone of
countlatestmaxsumunique custom_fieldsobject- Custom fields to attach to the billable metric. Example: {"key": "value"}
event_type_filterobject- An optional filtering rule to match the 'event_type' property of an event. Example: {"in_values": ["api_request"]}
group_keysarray- 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_keystring- 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_filtersarray- 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"]}]
sqlstring- 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
metronome_billable_metric_updateRename a billable metric.WriteUpdate Billable Metric
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.
- Idempotent
Inputs
billable_metric_idstringrequired- Billable metric ID (a UUID). Get it from metronome_billable_metrics_list. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
namestringrequired- The new name of the metric. Example: CPU hours
metronome_billing_provider_set_upSet up an account-level AWS, Azure or GCP marketplace billing provider with its delivery method and configuration.WriteSet Up Billing Provider
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.
Inputs
billing_providerstringrequired- The billing provider set for this configuration. Example: aws_marketplaceone of
aws_marketplaceazure_marketplacegcp_marketplace configurationobjectrequired- 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_methodstringrequired- The method to use for delivering invoices for this configuration. Example: direct_to_billing_providerone of
direct_to_billing_provideraws_sqsaws_sns idempotency_keystring- 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
metronome_commit_createCreate a customer-level prepaid or postpaid commit that can apply across contracts, with its product, priority, access schedule and optional invoice schedule.WriteCreate Customer Commit
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.
Inputs
access_scheduleobjectrequired- 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_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
prioritynumberrequired- If multiple credits or commits are applicable, the one with the lower priority will apply first. Example: 100
product_idstringrequired- 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
typestringrequired- 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: PREPAIDone of
PREPAIDPOSTPAID applicable_contract_idsarray- Which contract the commit applies to. If not provided, the commit applies to all contracts. Example: ["9b85c1c1-5238-4f2a-a409-61412905e1e1"]
applicable_product_idsarray- 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_tagsarray- 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_fieldsobject- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
descriptionstring- Used only in UI/API. It is not exposed to end customers. Example: Created by the Scalekit connector
invoice_contract_idstring- 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_scheduleobject- 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"}]}
namestring- displayed on invoices. Example: My Commit
netsuite_sales_order_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
rate_typestring- 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_RATEone of
COMMIT_RATELIST_RATE salesforce_opportunity_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
specifiersarray- 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_keystring- 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
metronome_commit_editEdit a contract-level or customer-level commit: name, description, access or invoice schedule, applicable products or contracts, product, priority, rate type or hierarchy settings.WriteEdit Commit
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.
Inputs
commit_idstringrequired- ID of the commit to edit. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
customer_idstringrequired- ID of the customer whose commit is being edited. Example: 4c91c473-fc12-445a-9c38-40421d47023f
access_scheduleobject- 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_idsarray- 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_idsarray- 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_tagsarray- 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"]
descriptionstring- Updated description for the commit. Example: Created by the Scalekit connector
hierarchy_configurationobject- Optional configuration for commit hierarchy access control. Example: {"child_access": {"type": "ALL"}}
idempotency_keystring- 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_idstring- ID of contract to use for invoicing. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
invoice_scheduleobject- 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"}]}
namestring- Updated name for the commit. Example: Standard
prioritynumber- If multiple commits are applicable, the one with the lower priority will apply first. Example: 100
product_idstring- Product ID (a UUID). Get it from metronome_products_list. Example: 2e30f074-d04c-412e-a134-851ebfa5ceb2
rate_typestring- 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_RATEone of
LIST_RATECOMMIT_RATE specifiersarray- 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"]}]
metronome_commit_end_date_updateMove a prepaid commit's access end date or invoice schedule end date earlier, to end it before its original schedule.WriteUpdate Commit End Date
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.
Inputs
commit_idstringrequired- ID of the commit to update. Only supports "PREPAID" commits. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
customer_idstringrequired- ID of the customer whose commit is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
access_ending_beforestring- 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_keystring- 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_beforestring- 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
metronome_commit_trueup_disableTurn off the true-up invoice for a postpaid commit, so Metronome does not bill the unused commitment at the end of the term.WriteDisable Commit True-Up
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.
Inputs
commit_idstringrequired- ID of the commit to update. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
contract_idstringrequired- ID of the contract that the commit is on. Example: 7526bacf-f08a-47af-b473-bc57b88890e1
customer_idstringrequired- ID of the customer whose commit is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
amendment_idstring- If applicable, the amendment ID that the commit is on. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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
metronome_contract_createCreate 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.WriteCreate Contract
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).
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
starting_atstringrequired- inclusive contract start time. Example: 2026-01-01T00:00:00.000Z
billing_provider_configurationobject- 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"}
commitsarray- 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_overridesarray- 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"}]
creditsarray- 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_fieldsobject- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
discountsarray- 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_beforestring- exclusive contract end time. Example: 2027-01-01T00:00:00.000Z
hierarchy_configurationobject- 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_prioritizationstring- 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_MULTIPLIERone of
LOWEST_MULTIPLIEREXPLICIT namestring- Display name for the contract. Example: Acme Corp 2026 agreement
net_payment_terms_daysnumber- Number of days after the invoice issue date that payment is due, for example 30 for net-30 terms. Example: 30
netsuite_sales_order_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
overridesarray- 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_aliasstring- Selects the package linked to the specified alias as of the contract's start date. Mutually exclusive with package_id. Example: startup-plan
package_customizationsobject- 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_idstring- 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_configurationobject- 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_servicesarray- 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_aliasstring- Selects the rate card linked to the specified alias as of the contract's start date. Example: standard-2026
rate_card_idstring- Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
recurring_commitsarray- 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_creditsarray- 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_royaltiesarray- 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_configurationobject- 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_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
scheduled_chargesarray- 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_invoicesstring- 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: ALLone of
ALL spend_threshold_configurationobject- 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_trackersarray- 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"]}]}]
subscriptionsarray- 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_valuenumber- This field's availability is dependent on your client's configuration. Example: 100
transitionobject- 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_keystring- 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_filterobject- 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_scheduleobject- 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"}
metronome_contract_editEdit 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.WriteEdit Contract
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.
Inputs
contract_idstringrequired- ID of the contract being edited. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- ID of the customer whose contract is being edited. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
add_billing_provider_configuration_updateobject- 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_commitsarray- 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_overridesarray- 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_creditsarray- 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_discountsarray- 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_overridesarray- 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_configurationobject- 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_servicesarray- 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_commitsarray- 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_creditsarray- 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_royaltiesarray- 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_updateobject- 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_chargesarray- 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_configurationobject- 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_trackersarray- 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_subscriptionsarray- 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_invoiceboolean- 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_commitsarray- IDs of commits to archive. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
archive_creditsarray- IDs of credits to archive. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
archive_scheduled_chargesarray- IDs of scheduled charges to archive. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
archive_spend_trackersarray- Aliases of spend trackers to archive. Example: ["monthly-spend"]
remove_overridesarray- IDs of overrides to remove. Example: [{"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
uniqueness_keystring- Optional uniqueness key to prevent duplicate contract edits. Example: sktest-edit-0001
update_commitsarray- 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_datestring- RFC 3339 timestamp indicating when the contract will end (exclusive). Example: 2027-01-01T00:00:00.000Z
update_contract_namestring- Value to update the contract name to. If not provided, the contract name will remain unchanged. Example: Acme Corp 2026 agreement (amended)
update_creditsarray- 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_daysnumber- Number of days after issuance of invoice after which the invoice is due (e.g. Net 30). Example: 100
update_prepaid_balance_threshold_configurationobject- 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_commitsarray- 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_creditsarray- 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_chargesarray- 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_configurationobject- 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_subscriptionsarray- Optional list of subscriptions to update. Example: [{"subscription_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"}]
metronome_contract_end_date_updateSet, move or remove a contract's end date.WriteUpdate Contract End Date
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.
Inputs
contract_idstringrequired- ID of the contract to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- ID of the customer whose contract is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
allow_ending_before_finalized_invoiceboolean- 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_beforestring- 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_keystring- 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
metronome_contract_invoice_issue_date_updateChange the issue date of a DRAFT invoice on a contract without changing future billing periods.WriteUpdate Invoice Issue Date
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.
Inputs
invoice_idstringrequired- ID of the invoice to update. The invoice must still be in DRAFT status. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
issue_datestringrequired- 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_keystring- 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
metronome_contract_usage_filter_setRoute usage to a contract by group key and values from a start date, for customers with several contracts that have overlapping rates.WriteSet Contract Usage Filter
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.
Inputs
contract_idstringrequired- Metronome contract ID (a UUID). Get it from metronome_contracts_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
group_keystringrequired- Event property used to route usage to this contract, for example region. Example: region
group_valuesarrayrequired- Values of the group key whose usage goes to this contract. Example: ["us-east-1", "us-west-2"]
starting_atstringrequired- When the filter takes effect, RFC 3339 on an hour boundary. Example: 2026-02-01T00:00:00.000Z
idempotency_keystring- 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
metronome_credit_createCreate a customer-level credit (for example a promotional credit) with its product, priority and access schedule.WriteCreate Customer Credit
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.
Inputs
access_scheduleobjectrequired- 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_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
prioritynumberrequired- If multiple credits or commits are applicable, the one with the lower priority will apply first. Example: 100
product_idstringrequired- Product ID (a UUID). Get it from metronome_products_list. Example: f14d6729-6a44-4b13-9908-9387f1918790
applicable_contract_idsarray- Which contract the credit applies to. If not provided, the credit applies to all contracts. Example: ["9b85c1c1-5238-4f2a-a409-61412905e1e1"]
applicable_product_idsarray- 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_tagsarray- 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_fieldsobject- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
descriptionstring- Used only in UI/API. It is not exposed to end customers. Example: Created by the Scalekit connector
namestring- displayed on invoices. Example: My Credit
netsuite_sales_order_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
rate_typestring- 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_RATEone of
COMMIT_RATELIST_RATE salesforce_opportunity_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
specifiersarray- 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_keystring- 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
metronome_credit_editEdit a contract-level or customer-level credit: name, description, access schedule, applicable products or contracts, product, priority, rate type or hierarchy settings.WriteEdit Credit
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.
Inputs
credit_idstringrequired- ID of the credit to edit. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
customer_idstringrequired- ID of the customer whose credit is being edited. Example: 4c91c473-fc12-445a-9c38-40421d47023f
access_scheduleobject- 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_idsarray- 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_idsarray- 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_tagsarray- 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"]
descriptionstring- Updated description for the credit. Example: Created by the Scalekit connector
hierarchy_configurationobject- Optional configuration for credit hierarchy access control. Example: {"child_access": {"type": "ALL"}}
idempotency_keystring- 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
namestring- Updated name for the credit. Example: Standard
prioritynumber- If multiple commits are applicable, the one with the lower priority will apply first. Example: 100
product_idstring- Product ID (a UUID). Get it from metronome_products_list. Example: 2e30f074-d04c-412e-a134-851ebfa5ceb2
rate_typestring- 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_RATEone of
LIST_RATECOMMIT_RATE specifiersarray- 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"]}]
metronome_credit_end_date_updateMove a credit's access end date earlier, to end it before its original schedule.WriteUpdate Credit End Date
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.
Inputs
access_ending_beforestringrequired- 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_idstringrequired- ID of the commit to update. Example: 6162d87b-e5db-4a33-b7f2-76ce6ead4e85
customer_idstringrequired- ID of the customer whose credit is to be updated. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
idempotency_keystring- 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
metronome_custom_field_key_createAdd a custom field key for an entity type, optionally requiring each value to be unique.WriteCreate Custom Field Key
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.
Inputs
enforce_uniquenessbooleanrequired- Set to true to require every value of this key to be unique across objects of the entity type. Example: false
entitystringrequired- Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customerone of
alertbillable_metricchargecommitcontract_creditcontract_productcontractcustomerdiscountinvoiceprofessional_serviceproductrate_cardscheduled_chargesubscriptionpackage_commitpackage_creditpackage_subscriptionpackage_scheduled_charge keystringrequired- Name of the new custom field key. Example: region
idempotency_keystring- 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
metronome_custom_field_values_setSet custom field values on one entity, overwriting matching keys and keeping the others.WriteSet Custom Field Values
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).
Inputs
custom_fieldsobjectrequired- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"region": "emea", "tier": "gold"}
entitystringrequired- Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customerone of
alertbillable_metricchargecommitcontract_creditcontract_productcontractcustomerdiscountinvoiceprofessional_serviceproductrate_cardscheduled_chargesubscriptionpackage_commitpackage_creditpackage_subscriptionpackage_scheduled_charge entity_idstringrequired- 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_keystring- 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
metronome_customer_alert_resetClear the state of one threshold notification for a customer and evaluate it again against current data.WriteReset Customer Threshold Notification
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.
Inputs
alert_idstringrequired- The Metronome ID of the threshold notification. Example: 5e8691bf-b22a-4672-922d-f80eee940f01
customer_idstringrequired- The Metronome ID of the customer. Example: 4c83caf3-8af4-44e2-9aeb-e290531726d9
idempotency_keystring- 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
metronome_customer_billing_configs_setCreate one or more billing provider configurations for customers.WriteSet Customer Billing Configurations
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.
Inputs
dataarrayrequired- 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_keystring- 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
metronome_customer_config_updateUpdate a customer's integration configuration, currently the Salesforce account ID linked to the customer.WriteUpdate Customer Configuration
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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_idstring- The Salesforce account ID for the customer. Example: 0015500001WO1ZiABL
metronome_customer_createCreate 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.WriteCreate Customer
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.
Inputs
namestringrequired- This will be truncated to 160 characters if the provided name is longer. Example: Acme Corp
custom_fieldsobject- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
customer_billing_provider_configurationsarray- 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_configurationsarray- 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_idstring- (deprecated, use ingest_aliases instead) an alias that can be used to refer to this customer in usage events. Example: acct_12345
idempotency_keystring- 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_aliasesarray- Aliases that can be used to refer to this customer in usage events. Example: ["team@example.com", "acct_12345"]
metronome_customer_dashboard_url_getGenerate a signed, iframe-ready URL for one of Metronome's customer dashboards (invoices, usage, or commits and credits), with optional display options and colors.WriteGet Embeddable Customer Dashboard URL
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: 4db51251-61de-4bfe-b9ce-495e244f3491
dashboardstringrequired- The type of dashboard to retrieve. Example: invoicesone of
invoicesusagecommits_and_credits color_overridesarray- Optional list of colors to override. Example: [{"name": "Gray_dark", "value": "#ff0000"}]
dashboard_optionsarray- Optional dashboard specific options. Example: [{"key": "show_zero_usage_line_items", "value": "false"}, {"key": "invoice_status_filter", "value": "FINALIZED"}]
metronome_customer_ingest_aliases_setReplace the full list of ingest aliases on a customer.WriteSet Customer Ingest Aliases
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
ingest_aliasesarrayrequired- 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_keystring- 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
metronome_customer_name_updateChange a customer's display name, which appears on invoices and in the Metronome app.WriteUpdate Customer Name
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.
Inputs
customer_idstringrequired- Metronome customer ID (a UUID). Get it from metronome_customers_list or metronome_customer_create. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
namestringrequired- The new name for the customer. This will be truncated to 160 characters if the provided name is longer. Example: Example, Inc.
idempotency_keystring- 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
metronome_events_ingestSend up to 100 usage events to Metronome.WriteIngest Usage Events
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.
Inputs
eventsarrayrequired- 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_keystring- 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
metronome_historical_invoices_createCreate usage invoices for past billing periods on contracts, with your own usage line items, quantities and date ranges.WriteCreate Historical Invoices
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.
Inputs
invoicesarrayrequired- 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}]}]
previewbooleanrequired- Set to true to validate and return the invoices without creating them. Set to false to create them. Example: true
idempotency_keystring- 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
metronome_invoice_regenerateRegenerate a voided invoice, recalculating it with current rates, available balances and fees.WriteRegenerate Invoice
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.
Inputs
idstringrequired- The invoice id to regenerate. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
idempotency_keystring- 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
metronome_notification_createCreate an offset lifecycle event notification that fires a set time before or after a lifecycle event.WriteCreate Offset Notification
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.
Inputs
namestringrequired- The name for this offset notification configuration. Example: 7 days before contract start
policyobjectrequired- 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_keystring- Optional uniqueness key to prevent duplicate notification configurations. Example: contract-start-notification-823j7fqzo1
metronome_notification_editEdit an offset notification's policy or enabled state, or turn a system notification type on or off.WriteEdit Notification
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.
Inputs
policyobjectrequired- Updated policy configuration. The policy.type must match the existing lifecycle event type. Example: {"type": "contract.start", "offset": "P2D"}
idstring- The ID of the notification configuration to edit. Not provided when updating the configuration for system events. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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_enabledboolean- 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
metronome_package_createCreate a package: a reusable set of time-relative contract terms (rate card, commits, credits, overrides, scheduled charges, subscriptions) to provision customers with standard pricing.WriteCreate Package
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).
Inputs
namestringrequired- Package name. Example: Startup plan
aliasesarray- 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_providerstring- Billing provider that contracts from this package are billed through, such as stripe or aws_marketplace. Example: stripeone of
aws_marketplaceazure_marketplacegcp_marketplacestripenetsuite commitsarray- 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_namestring- Name given to contracts created from this package. Example: Startup plan contract
creditsarray- 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_methodstring- How invoices are delivered to the billing provider, such as direct_to_billing_provider. Example: direct_to_billing_providerone of
direct_to_billing_provideraws_sqstackleaws_sns durationobject- 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_prioritizationstring- 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_MULTIPLIERone of
LOWEST_MULTIPLIEREXPLICIT net_payment_terms_daysnumber- Number of days after the invoice issue date that payment is due, for example 30 for net-30 terms. Example: 30
overridesarray- 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_configurationobject- 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_aliasstring- Selects the rate card linked to the specified alias as of the contract's start date. Example: standard-2026
rate_card_idstring- Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
recurring_commitsarray- 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_creditsarray- 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_chargesarray- 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_invoicesstring- 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: ALLone of
ALL spend_threshold_configurationobject- 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_trackersarray- 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"]}]}]
subscriptionsarray- 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_keystring- 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_scheduleobject- 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"}
metronome_pricing_unit_createCreate a custom pricing unit for charging in a non-fiat unit, for example AI credits.WriteCreate Pricing Unit
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.
Inputs
namestringrequired- The name of the custom pricing unit. This will appear on invoices. Example: AI credits
idempotency_keystring- 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
metronome_product_createCreate 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.WriteCreate Product
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).
Inputs
namestringrequired- displayed on invoices. Example: API requests
typestringrequired- 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: USAGEone of
FIXEDUSAGECOMPOSITESUBSCRIPTIONPROFESSIONAL_SERVICEPRO_SERVICE billable_metric_idstring- Required for USAGE products. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
composite_product_idsarray- Required for COMPOSITE products. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
composite_scopestring- 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: customerone of
customercontract composite_tagsarray- Required for COMPOSITE products. Example: ["compute"]
custom_fieldsobject- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
exclude_free_usageboolean- 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_keystring- 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_spendboolean- Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false. Example: false
is_refundableboolean- This field's availability is dependent on your client's configuration. Defaults to true. Example: false
netsuite_internal_item_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
netsuite_overage_item_idstring- This field's availability is dependent on your client's configuration. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
presentation_group_keyarray- 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_keyarray- 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_conversionobject- 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_roundingobject- 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_granularitystring- 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: HOURone of
HOURSERVICE_PERIOD tagsarray- Tags on the product. Commits, credits, overrides and composite products can target products by tag. Example: ["compute", "api"]
metronome_product_updateSchedule 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.WriteUpdate Product
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.
Inputs
product_idstringrequired- ID of the product to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
starting_atstringrequired- 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_idstring- Available for USAGE products only. If not provided, defaults to product's current billable metric. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
composite_product_idsarray- Available for COMPOSITE products only. If not provided, defaults to product's current composite_product_ids. Example: ["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"]
composite_tagsarray- Available for COMPOSITE products only. If not provided, defaults to product's current composite_tags. Example: ["compute"]
exclude_free_usageboolean- 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_keystring- 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_spendboolean- Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false. Example: false
is_refundableboolean- Defaults to product's current refundability status. This field's availability is dependent on your client's configuration. Example: false
namestring- displayed on invoices. If not provided, defaults to product's current name. Example: My Updated Product
netsuite_internal_item_idstring- 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_idstring- 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_keyarray- 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_keyarray- 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_conversionobject- 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_roundingobject- 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_granularitystring- 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: HOURone of
HOURSERVICE_PERIOD tagsarray- If not provided, defaults to product's current tags. Example: ["compute"]
metronome_rate_card_createCreate a rate card with a name, optional description, fiat pricing unit, custom pricing unit conversions and aliases.WriteCreate Rate Card
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.
Inputs
namestringrequired- Used only in UI/API. It is not exposed to end customers. Example: Standard pricing 2026
aliasesarray- 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_conversionsarray- Required when using custom pricing units in rates. Example: [{"custom_credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "fiat_per_custom_credit": 2}]
custom_fieldsobject- Custom fields to be added eg. { "key1": "value1", "key2": "value2" }. Example: {"key": "value"}
descriptionstring- Description of the rate card. Example: Standard 2026 list prices
fiat_credit_type_idstring- 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_keystring- 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
metronome_rate_card_products_moveMove specific products to new positions in a rate card's product order, which sets the order on invoices.WriteMove Rate Card Products
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.
Inputs
product_movesarrayrequired- 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_idstringrequired- ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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
metronome_rate_card_products_order_setSet the full order of products on a rate card, which is the order they appear on customers' invoices.WriteSet Rate Card Products Order
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.
Inputs
product_orderarrayrequired- Product IDs in the order they should appear on invoices. Example: ["2e30f074-d04c-412e-a134-851ebfa5ceb2", "1f4d2b6e-8c3a-4f5e-9a7b-2c1d0e9f8a7b"]
rate_card_idstringrequired- ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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
metronome_rate_card_rate_addAdd 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.WriteAdd Rate to Rate Card
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.
Inputs
entitledbooleanrequired- 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_idstringrequired- ID of the product to add a rate for. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
rate_card_idstringrequired- ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
rate_typestringrequired- 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: FLATone of
FLATPERCENTAGESUBSCRIPTIONTIEREDTIERED_PERCENTAGECUSTOM starting_atstringrequired- inclusive effective date. Example: 2026-01-01T00:00:00.000Z
billing_frequencystring- Optional. Frequency to bill subscriptions with. Required for subscription type products with Flat rate. Example: MONTHLYone of
MONTHLYQUARTERLYSEMI_ANNUALANNUALWEEKLY commit_rateobject- 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_idstring- 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_rateobject- Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. Example: {"rate_key": "premium"}
ending_beforestring- exclusive end date. Example: 2026-02-01T00:00:00.000Z
idempotency_keystring- 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_proratedboolean- Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. Example: false
minimum_configobject- 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}
pricenumber- 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_valuesobject- Optional. List of pricing group key value pairs which will be used to calculate the price. Example: {"key": "value"}
quantitynumber- Default quantity. For SUBSCRIPTION rate_type, this must be >=0. Example: 100
tiersarray- Only set for TIERED rate_type. Example: [{"price": 100}]
metronome_rate_card_rates_addAdd several rates to a rate card in one call.WriteAdd Rates to Rate Card
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.
Inputs
rate_card_idstringrequired- Rate card ID (a UUID). Get it from metronome_rate_cards_list. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
ratesarrayrequired- 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_keystring- 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
metronome_rate_card_updateUpdate a rate card's name, description or aliases, or add credit type conversions.WriteUpdate Rate Card
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.
Inputs
rate_card_idstringrequired- ID of the rate card to update. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
add_credit_type_conversionsarray- 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}]
aliasesarray- 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"}]
descriptionstring- New description for the rate card. Example: Standard 2026 list prices
idempotency_keystring- 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
namestring- Used only in UI/API. It is not exposed to end customers. Example: My Updated Rate Card
metronome_threshold_commit_releaseReport the outcome of an external payment attempt for a threshold billing commit, which releases the pending commit when paid or cancels it when failed.WriteRelease Threshold Billing Commit
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.
Inputs
outcomestringrequired- The outcome of the external payment gate. Example: paidone of
paidfailed workflow_idstringrequired- ID of the workflow to continue. Example: 5576ba1f-4a33-b473-3f05-6162d87b4a33
idempotency_keystring- 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
metronome_alert_archiveArchive a threshold notification so it stops being evaluated for all customers, optionally releasing its uniqueness key.DestructiveArchive Threshold Notification
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.
Inputs
idstringrequired- The Metronome ID of the threshold notification. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
idempotency_keystring- 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_keyboolean- If true, resets the uniqueness key on this threshold notification so it can be re-used. Example: false
metronome_billable_metric_archiveArchive a billable metric so it cannot be used by new products.DestructiveArchive Billable Metric
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.
Inputs
idstringrequired- ID of the billable metric to archive. Get it from metronome_billable_metrics_list. Example: 8deed800-1b7a-495d-a207-6c52bac54dc9
idempotency_keystring- 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
metronome_commit_archiveArchive a contract-level or customer-level commit, keeping its history.DestructiveArchive Commit
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.
Inputs
commit_idstringrequired- ID of the commit to archive. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
customer_idstringrequired- ID of the customer whose commit is being archived. Example: 4c91c473-fc12-445a-9c38-40421d47023f
idempotency_keystring- 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
metronome_contract_archiveArchive a contract and all its terms.DestructiveArchive Contract
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.
Inputs
contract_idstringrequired- ID of the contract to archive. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
customer_idstringrequired- ID of the customer whose contract is to be archived. Example: 13117714-3f05-48e5-a6e9-a66093f13b4d
void_invoicesbooleanrequired- If false, the existing finalized invoices will remain after the contract is archived. Example: true
idempotency_keystring- 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
metronome_credit_archiveArchive a contract-level or customer-level credit, keeping its history.DestructiveArchive Credit
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.
Inputs
credit_idstringrequired- ID of the credit to archive. Example: 5e7e82cf-ccb7-428c-a96f-a8e4f67af822
customer_idstringrequired- ID of the customer whose credit is being archived. Example: 4c91c473-fc12-445a-9c38-40421d47023f
idempotency_keystring- 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
metronome_custom_field_key_deleteRemove a custom field key from an entity type.DestructiveDelete Custom Field Key
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.
Inputs
entitystringrequired- Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customerone of
alertbillable_metricchargecommitcontract_creditcontract_productcontractcustomerdiscountinvoiceprofessional_serviceproductrate_cardscheduled_chargesubscriptionpackage_commitpackage_creditpackage_subscriptionpackage_scheduled_charge keystringrequired- Name of the custom field key to remove. Example: region
idempotency_keystring- 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
metronome_custom_field_values_deleteRemove some custom field values from one entity, keeping its other fields.DestructiveDelete Custom Field Values
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.
Inputs
entitystringrequired- Type of Metronome object the custom field belongs to, such as customer, contract, product, commit, rate_card or billable_metric. Example: customerone of
alertbillable_metricchargecommitcontract_creditcontract_productcontractcustomerdiscountinvoiceprofessional_serviceproductrate_cardscheduled_chargesubscriptionpackage_commitpackage_creditpackage_subscriptionpackage_scheduled_charge entity_idstringrequired- 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
keysarrayrequired- Custom field keys whose values to remove from the object. Example: ["region"]
idempotency_keystring- 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
metronome_customer_archiveArchive a customer.DestructiveArchive Customer
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.
Inputs
idstringrequired- 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_keystring- 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
metronome_customer_billing_configs_archiveArchive billing provider configurations for a customer.DestructiveArchive Customer Billing Configurations
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.
Inputs
customer_billing_provider_configuration_idsarrayrequired- Array of billing provider configuration IDs to archive. Example: ["4db51251-61de-4bfe-b9ce-495e244f3491", "4db51251-61de-4bfe-b9ce-495e244f3491"]
customer_idstringrequired- The customer ID the billing provider configurations belong to. Example: 20a060d1-aa80-41d4-8bb2-4f3091b93903
idempotency_keystring- 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
metronome_invoice_voidVoid an invoice so it is not collected and is removed from the customer's billing.DestructiveVoid Invoice
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.
Inputs
idstringrequired- The invoice id to void. Example: 6a37bb88-8538-48c5-b37b-a41c836328bd
idempotency_keystring- 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
metronome_notification_archiveArchive an offset lifecycle event notification so it is no longer processed.DestructiveArchive Offset Notification
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.
Inputs
idstringrequired- The ID of the offset lifecycle event notification configuration to archive. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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
metronome_package_archiveArchive a package so it can no longer be used for new contracts.DestructiveArchive Package
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.
Inputs
package_idstringrequired- ID of the package to archive. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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
metronome_pricing_unit_archiveArchive a custom pricing unit so it no longer appears in pricing unit selectors by default.DestructiveArchive Pricing Unit
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.
Inputs
idstringrequired- ID of the custom pricing unit to archive. Get it from metronome_pricing_units_list. Example: fa2f1b3d-9d52-4951-a099-25991fd394d6
idempotency_keystring- 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
metronome_product_archiveArchive a product so it can no longer be used for new rates.DestructiveArchive Product
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.
Inputs
product_idstringrequired- ID of the product to be archived. Example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
idempotency_keystring- 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
metronome_rate_card_archiveArchive a rate card so it can no longer be used for new contracts.DestructiveArchive Rate Card
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.
Inputs
idstringrequired- ID of the rate card to archive. Get it from metronome_rate_cards_list. Example: 12b21470-4570-40df-8998-449d0b0bc52f
idempotency_keystring- 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
No tools match.