/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.
license: MIT

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](https://docs.metronome.com/guides/events/send-usage-events.md), the [API quickstart](https://docs.metronome.com/guides/get-started/api-quickstart.md), the [Ingest API reference](https://docs.metronome.com/api-reference/usage/ingest-events.md), and [Set ingest aliases](https://docs.metronome.com/api-reference/customers/create-or-update-customer-ingest-aliases.md) | | Defining what to measure | Billable Metrics API | [Create billable metrics](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-billable-metrics.md) | | Enterprise pricing agreements | Contracts + Rate Cards | [Provision a customer contract](https://docs.metronome.com/guides/implement-metronome/core-concepts/provision-contract.md), [Create and manage rate cards](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-manage-rate-cards.md), and the [Create a contract](https://docs.metronome.com/api-reference/contracts/create-a-contract.md) and [Add rates](https://docs.metronome.com/api-reference/rate-cards/add-rates.md) API references | | Mid-term contract changes | Contract Edits | [Edit a contract](https://docs.metronome.com/guides/pricing-packaging/make-pricing-changes/edit-contract.md), [Contract edits and overrides](https://docs.metronome.com/guides/pricing-packaging/make-pricing-changes/edit-or-override-a-contract.md), and [Manage contract lifecycle](https://docs.metronome.com/guides/customers-billing/manage-customers/manage-customer-lifecycle.md) | | Invoice lifecycle and finalization | Invoices API | [How Metronome invoices work](https://docs.metronome.com/guides/implement-metronome/core-concepts/how-invoicing-works.md) | | Prepaid or postpaid commitments and one-off top-ups | Commits + Credits | [Apply credits and commits to contracts](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/create-a-pre-paid-commit.md) and [Payment-gated commits](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/manual-payment-gated-commits.md) | | Syncing invoices to Stripe | Stripe billing provider config | [Invoice with Stripe](https://docs.metronome.com/integrations/invoice-integrations/stripe.md) | | Prepaid balances, auto-recharge, spend alerts, and thresholds | Notifications API | [Set prepaid balance thresholds](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/prepaid-balance-thresholds.md), [Enforce spend thresholds](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/set-customer-spend-control.md), and [Threshold notifications](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/alerts.md) |

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](https://docs.metronome.com/llms.txt) 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](https://docs.metronome.com/.well-known/skills/stripe-to-metronome-migration/SKILL.md) | 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](https://docs.metronome.com/.well-known/skills/metronome-group-keys/SKILL.md) | 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](https://docs.me