metronome

Metronome API base: https://api.metronome.com. Authenticate with a Bearer token in the Authorization header. Always use Contracts (not legacy Plans) for new integrations.

Integration routing

Building…	Recommended API	Details
Ingesting usage events	POST /v1/ingest (batch)	Send usage events, the API quickstart, the Ingest API reference, and Set ingest aliases
Defining what to measure	Billable Metrics API	Create billable metrics
Enterprise pricing agreements	Contracts + Rate Cards	Provision a customer contract, Create and manage rate cards, and the Create a contract and Add rates API references
Mid-term contract changes	Contract Edits	Edit a contract, Contract edits and overrides, and Manage contract lifecycle
Invoice lifecycle and finalization	Invoices API	How Metronome invoices work
Prepaid or postpaid commitments and one-off top-ups	Commits + Credits	Apply credits and commits to contracts and Payment-gated commits
Syncing invoices to Stripe	Stripe billing provider config	Invoice with Stripe
Prepaid balances, auto-recharge, spend alerts, and thresholds	Notifications API	Set prepaid balance thresholds, Enforce spend thresholds, and Threshold notifications

Read the linked page before answering any integration question or writing code; the links return plain Markdown. If no row fits, use the documentation index to find the right page, and append .md to the page URL to fetch it as Markdown.

Operational workflows

Metronome publishes step-by-step skills for the tasks below. Read the linked skill in full before starting the task. Several of them create real Metronome objects through the API using the token in the environment: confirm which environment that token targets (sandbox and production share https://api.metronome.com; the token determines the environment) and get the user’s explicit confirmation before any write. Where a step also writes to Stripe, as the migration cutover does when it ends subscriptions, identify the Stripe account and mode behind the Stripe key (for example with GET /v1/account) and confirm those writes separately.

Task	Metronome skill	What it does
Migrating from Stripe Billing Meters, Subscriptions, and Credit Grants to Metronome	stripe-to-metronome-migration	Changes production state when executed: creates Metronome customers, contracts, and credits, flips billable status, and ends Stripe subscriptions at cutover. Also covers scoping, concept mapping, group key design, the parallel run, and rollback.
Designing group_keys, pricing_group_key, and presentation_group_key for a billable metric	metronome-group-keys	Creates the billable metric and product after a confirmation gate. Sizes cardinality risk first: a compound key’s cost is the product of each dimension’s cardinality, and group_keys is immutable.
Setting up Metronome from scratch: billable metrics, products, rate card, customer, and contract	metronome-setup-catalog	Creates objects. End-to-end setup from pricing intent to a verified draft invoice.
Creating a customer record	metronome-create-customer	Creates objects. Duplicate check and preview, then POST /v1/customers with name, ingest alias, Salesforce ID, and Slack channel.
Creating a new contract from signed order-form terms	metronome-create-contract	Creates objects. Commits, credits, and rate overrides on a new contract, including commit-specific discounts; for an existing contract use Contract Edits (routing table above).
Billing an AI application for token usage	metronome-token-billing	Creates objects. Models AI plans, builds the managed rate card with your markup over Stripe’s model catalog, provisions the customer, and validates the Stripe and Metronome flow.
Self-serve (PLG) billing setup, pricing changes, and single-customer diagnostics, in business terms	metronome-plg-billing	Creates and changes objects in its start-billing and change-pricing modes; customer-story mode is a read-only diagnostic.
Customer health reviews for Metronome CSMs: anomalies, commit burn, portfolio briefing, renewal prep	metronome-csm-reviews	Read-only. Written for Metronome’s account team rather than for building an integration.

Critical rules

• Always read the linked documentation page before naming a Metronome endpoint, field, or amount. Endpoint paths, request shapes, and units can be misremembered; the routing table above points to the page for each task.
• Always use Contracts, not legacy Plans, for new customers. Plans are deprecated and lack rate card overrides, commits, and flexible scheduling. An existing Plans integration keeps working: don’t propose migrating it unless asked, and when migrating move credit balances with POST /v1/credits/migrateToContracts.
• Always use Edits (POST /v2/contracts/edit), not deprecated Amendments (/v1/contracts/amend), for mid-term changes to a contract (new products, commits, overrides). Edits are the actively invested path and required for v2 subscription features. Create a new contract with transition: {type: "renewal", from_contract_id} only for renewals.
• Always use batch ingestion (POST /v1/ingest with a bare JSON array of 1 to 100 event objects as the request body, not wrapped in an object) for production workloads. Single-event ingestion is acceptable only for testing. A 200 means the events were accepted, not rated: events whose event_type matches no billable metric are stored but excluded from usage, so create billable metrics before sending.
• Always include a unique transaction_id on every event, fixed when the event is recorded and re-sent unchanged on every retry: a UUID stored with the event, or a value derived from the source record. This is the idempotency key that prevents double-counting on retries; an ID regenerated per attempt defeats it.
• Always deliver usage for a billing period before its grace period ends (24 hours after billing_period_end_date by default). A finalized invoice ignores late events and can only be corrected by voiding and regenerating it; if your pipeline’s worst-case lag exceeds the grace period, ask Metronome support to lengthen it (it isn’t configurable through the API).
• Always set a usage_filter (group_key and group_values) on each contract when a customer has more than one concurrent contract, so usage is rated on one contract instead of all of them. The group key must be a group key on the streaming billable metric (an event property for SQL metrics).
• Never schedule a contract-level commit or credit access segment past the contract’s ending_before. Usage after the contract ends isn’t rated on it, so balance released after that date is stranded; end the last segment at the contract term and use rollover_fraction to carry a remaining balance into a renewal.
• Never put applicable_product_ids, applicable_product_tags, or specifiers on a spend_threshold_configuration commit. Spend-threshold commits apply to all usage and take only product_id, name, description, and priority; only prepaid_balance_threshold_configuration commits accept product filters.
• Never process multiple Metronome invoices for the same Stripe customer simultaneously. Concurrent processing causes race conditions on pending line items.
• Never hardcode pricing directly in contracts. Define pricing in rate cards and use contract-level overrides for custom rates. This ensures un-overridden pricing stays current when the rate card changes.
• Always send USD amounts in cents. Metronome’s default USD credit type is denominated in cents (1000 is 10.00 USD) for thresholds, commits, credits, and rate or override prices; other currencies use whole units.
• Never finalize a Stripe invoice before tax calculation completes. If using Stripe Tax, Avalara, or Anrok, the tax provider must process the invoice before finalization.
• Never exceed 250 line items per Stripe invoice. Exceeding this limit causes all line items to collapse into a single entry, losing per-product detail. Plan product granularity and use composite products to aggregate high-cardinality metrics.
• Always reconcile payments against the Stripe invoice total, never the Metronome invoice total. Metronome sends untaxed line items and Stripe adds tax at finalization, so the Metronome total is pre-tax and can differ by sub-cent rounding.
• Never set NetSuite as both a contract’s billing_provider_configuration and its revenue_system_configuration. Use the billing configuration when NetSuite issues and collects the invoice; use the revenue system configuration only when another provider such as Stripe bills and NetSuite needs the invoice for revenue recognition.

Key documentation

When the user’s request doesn’t clearly fit a single domain above, consult:

• Metronome Documentation: Start here for any Metronome question.
• API Reference: Full endpoint reference.
• LLM-friendly doc index: Machine-readable documentation index.
• Stripe Integration Guide: Syncing Metronome invoices with Stripe.
• How Metronome works with Stripe: The Stripe guide to the integration patterns and what stays on Stripe.