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

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 (opens in a new tab) to find the right page, and append .md to the page URL to fetch it as Markdown.

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 (opens in a new tab): Start here for any Metronome question.
• API Reference (opens in a new tab): Full endpoint reference.
• LLM-friendly doc index (opens in a new tab): Machine-readable documentation index.
• Stripe Integration Guide (opens in a new tab): Syncing Metronome invoices with Stripe.
• How Metronome works with Stripe (opens in a new tab): The Stripe guide to the integration patterns and what stays on Stripe.