metronome

name: metronome description: >- Guides Metronome usage-based billing integration decisions — event ingestion (single and batch, idempotency, billable metrics), contract design (rate cards, overrides, dimensional pricing, products), invoicing lifecycle (grace periods, finalization, Stripe sync), credit and commit management (prepaid, postpaid, thresholds, auto-recharge), and Stripe integration (arrears invoicing, tax providers, line item limits). Use when building, modifying, or reviewing any Metronome integration — including ingesting usage events, creating customers, contracts, or rate cards, designing billable metric group keys, managing credits and commits, configuring invoicing, syncing invoices with Stripe Billing, billing AI applications for token usage, setting up self-serve (PLG) pricing, reviewing customer health, commit burn, portfolios, or renewals, or migrating from Stripe Billing Meters to 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 `rev