canonical: https://jentic.com/apis/metronome.com/metronome

# Metronome

Metronome is a usage-based billing platform that ingests product events, computes billable metrics, and generates invoices from custom rate cards and contracts. Its API supports the entire lifecycle of consumption pricing - defining billable metrics, registering customers, ingesting events, configuring contracts and credits, issuing invoices, and pushing data to downstream billing providers like Stripe. The API is consumed via 132 bearer-authenticated endpoints organised around customers, billable metrics, usage, products, rate cards, contracts, credits, invoices, and alerts.

## For AI agents

Ingest product usage events, compute billable metrics, manage rate cards and contracts, and produce invoices for consumption-based pricing programs.

## Scope

Does not collect payments, calculate sales tax, or store customer payment methods - use for usage metering, rate card pricing, and invoice generation only.

## Capabilities

- Ingest raw product events into Metronome with POST `/v1/ingest` for downstream metering
- Define billable metrics, products, and rate cards that translate usage into priced line items
- Create and update customers including ingest aliases that map your event payloads to Metronome customers
- Manage contracts, commits, and credits to support negotiated pricing and prepaid balances
- Issue invoices, list breakdowns, and push results to Stripe via the bundled billing-config integration
- Configure threshold alerts on customer usage and respond when limits are hit

## Use cases

### Usage-Based Billing for SaaS APIs

SaaS teams charging per API call or compute-second emit events to Metronome via `/v1/ingest`, define billable metrics that aggregate those events, and attach rate cards that price the aggregates. Metronome handles dedup, metering, and invoice generation, then forwards the result to Stripe so customers receive a payable invoice without the team building a metering pipeline.

Example prompt: Create a billable metric for API requests, register a customer with an ingest alias, post 1000 events to `/v1/ingest`, then GET `/v1/customers/{customer_id}/invoices` to confirm the line item.

### Negotiated Contracts and Prepaid Commits

Sales teams that close usage-based deals with negotiated minimums use the contracts, commits, and credits endpoints to encode the deal - e.g. 100,000 prepaid units expiring in 12 months at a tiered rate. Metronome draws down the commit as usage flows in and exposes remaining balance through customer-alerts, so account managers can prompt renewals before exhaustion.

Example prompt: Create a contract for customer 'cust_42' with a 100k unit commit, then POST `/v1/customer-alerts/create` at the 80% threshold to notify the account team.

### Threshold Alerts and Spend Caps

Finance and operations teams need real-time visibility when customers approach contractual or spend limits. `/v1/alerts/create` defines a threshold notification, `/v1/customer-alerts/list` returns the current status per customer, and `/v1/customer-alerts/reset` re-arms an alert after acknowledgement - useful for rolling monthly caps without rebuilding the rule each cycle.

Example prompt: Create a threshold alert at 90% of a customer's monthly commit, then POST `/v1/customer-alerts/get` to check whether it has triggered.

### Agent-Driven Usage Reporting

An autonomous agent producing customer health reports can query Metronome through Jentic to pull usage and invoice data on demand. The agent searches by intent, loads the schema for `/v1/usage` or `/v1/customers/{customer_id}/invoices`, and executes - with the bearer token kept inside your Jentic One instance for the entire run.

Example prompt: Search Jentic for 'get customer usage', load POST `/v1/usage` with grouping by customer, and execute for the last 30 days.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/ingest` | Ingest usage events for metering |
| POST | `/v1/billable-metrics` | Create a billable metric |
| POST | `/v1/customers` | Create a customer |
| GET | `/v1/customers/{customer_id}/invoices` | List invoices for a customer |
| POST | `/v1/usage` | Get batched usage data |
| POST | `/v1/alerts/create` | Create a threshold notification |
| POST | `/v1/client/billing-config/stripe` | Configure Stripe as the downstream billing provider |

## Key resources

- **Customers** — Create, list, and manage customers, ingest aliases, and customer-level configuration
- **Billable Metrics** — Define, list, and archive metrics that translate raw events into charged units
- **Usage** — Query batched and grouped usage data and search raw events
- **Products** — Manage products that map billable metrics to price points
- **Rate Cards** — Versioned pricing artefacts that customers and contracts reference
- **Contracts** — Negotiated deals including commits, overage rates, and effective dates
- **Credits and Commits** — Manage prepaid balances and drawdowns against usage
- **Invoices** — Issue invoices, list invoice breakdowns, and review historical billing
- **Alerts** — Create and reset threshold notifications on customer usage

## Why Jentic

- **Setup:** Wiring Metronome by hand means reading its bearer scheme, setting the Authorization header, and finding the right call among many usage, billing, and invoice operations yourself. Through Jentic you install once, import Metronome from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Metronome puts the customer id in the URL path (`/v1/customers/{customer_id}/invoices`), so a rule can pin your agent to one customer's data. You choose the operations it may call, so ingesting usage or creating alerts is not included unless you add it.
- **Credential handling:** Your Metronome bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'ingest a usage event' or 'get a customer's invoice', and Jentic returns the matching Metronome operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Payments and subscription management - collects on Metronome-issued invoices
- **Recurly** — Subscription billing platform with metered components
- **Paddle** — Merchant of record for SaaS billing and tax
- **Zuora** — Enterprise subscription and revenue billing platform

## FAQ

### What authentication does the Metronome API use?

Metronome uses HTTP bearer authentication - every request needs an Authorization header with your Metronome API token. Through Jentic the token is stored encrypted in the vault and added to requests at execution time.

### Can I ingest historical events with the Metronome API?

Yes. POST `/v1/ingest` accepts events with a timestamp field, so backfills are supported as long as the events fall within Metronome's accepted ingest window. For very old data, contact Metronome to extend the window.

### What are the rate limits for the Metronome API?

Metronome documents per-endpoint limits in their docs rather than the OpenAPI spec; ingest endpoints accept high-throughput batched payloads while admin endpoints have lower limits. Inspect 429 responses and back off, and use POST `/v1/ingest` batches rather than per-event calls.

### How do I send a usage event through Jentic?

Search Jentic for 'ingest a usage event into Metronome', load POST `/v1/ingest`, and execute with an event payload that includes transaction_id, customer_id, event_type, and timestamp. Jentic injects the bearer token from your stored credential.

### Does Metronome charge customer credit cards directly?

No - Metronome generates invoices and integrates with billing providers. Use the `/v1/client/billing-config/stripe` endpoints to push invoices into Stripe, where collection happens. Metronome itself is the metering and invoicing system.

### Can I retrieve invoice line-item breakdowns for a customer?

Yes - GET `/v1/customers/{customer_id}/invoices/breakdowns` returns the per-line breakdown for a customer's invoices, useful for finance reconciliation and customer-facing usage statements.

### Can I limit what my agent is allowed to do with the Metronome API?

Yes. Jentic One is self-hosted, so your own rules decide which Metronome operations and credentials the agent may use. Because Metronome puts the customer id in the URL path, such as GET `/v1/customers/{customer_id}/invoices`, you can pin the agent to a single customer's data. You also choose the exact operations it may call, so actions like POST `/v1/ingest` or POST `/v1/alerts/create` stay off limits unless you explicitly grant them.