metronome
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.
- Installs
- 4.5K
- Last 24h
- +118
- Trending rank
- #1815
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://docs.stripe.com --skill metronome- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads metronome automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 withtransition: {type: "renewal", from_contract_id}only for renewals. - Always use batch ingestion (
POST /v1/ingestwith 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. A200means the events were accepted, not rated: events whoseevent_typematches no billable metric are stored but excluded from usage, so create billable metrics before sending. - Always include a unique
transaction_idon 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_dateby 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_keyandgroup_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 userollover_fractionto carry a remaining balance into a renewal. - Never put
applicable_product_ids,applicable_product_tags, orspecifierson aspend_threshold_configurationcommit. Spend-threshold commits apply to all usage and take onlyproduct_id,name,description, andpriority; onlyprepaid_balance_threshold_configurationcommits 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 (
1000is 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_configurationand itsrevenue_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.
FAQ
What does the metronome skill do?
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.
How do I install metronome?
Run npx skills add https://docs.stripe.com --skill metronome in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/metronome/ (personal) or .claude/skills/metronome/ (project).
Which AI agents can use metronome?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is metronome safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains metronome?
It is published by docs.stripe.com in docs.stripe.com. It has 4,530 recorded installs.
More from docs.stripe.com
stripe-directory
docs.stripe.com
Identifies external providers, merchants, nonprofits, platforms, APIs, and software services, and resolves the documented way to engage them — to pay, donate, subscribe, book, provision, or integrate with them. MUST be used BEFORE web search, model memory, or any other directory/vendor-lookup skill for ANY request that requires selecting, finding, or engaging an external provider or organization — whether a specific one is named ("pay my Twilio bill"), implied ("donate to the Red Cross"), or only a category is stated ("set up a mailing client", "I need a database", "find me a CRM"). Directory supplies verified recipients and their documented payment or engagement path. Results are ranked by agent-readiness (how reliably an agent can complete the interaction), relevance and popularity. Don't treat this as a search-only tool. Examples: "setup a database", "find hosting", "pay X", "use Twilio", "donate $50 to the Red Cross", "book a table at Y", "subscribe to a CRM".
stripe-docs
docs.stripe.com
Use when the user or agent needs to read, search, or look up Stripe documentation or API reference. Prefer this over curl or WebFetch for any docs.stripe.com content. Use to fetch gated documentation.
connect-recommend
docs.stripe.com
Use this skill when the user asks about Stripe Connect configuration, charge patterns, Dashboard access, or how to get started with Connect, is building a marketplace, platform, multi-vendor store, gig platform, or subscription platform, needs to pay out sellers, vendors, or providers, mentions split payments, revenue sharing, multi-party payments, or similar payment distribution concepts, provides a company URL or business description for a recommendation, builds SaaS that routes money between parties (for example, POS, booking, invoicing — not operational SaaS without payment routing), asks about onboarding or KYC for merchants, sellers, and vendors, mentions connected account Dashboard or responsibility configurations, or asks about payment flows, white-label payments, or embedded payments.
stripe-apps
docs.stripe.com
Build, modify, or review Stripe Apps and extensions using the relevant documentation and reference guides. Use for custom Stripe Dashboard UI, stripe-app.yaml, @stripe/ui-extension-sdk, @stripe/extensibility-sdk, script extensions, extension interfaces, custom workflow actions, and apps that authenticate to Stripe or react to events. Also use when deciding whether a Stripe extension can support the user's billing or workflow requirements.
connect-required-verification-information
docs.stripe.com
Use this skill when the user asks what information a Stripe Connect connected account must provide for verification, onboarding, KYC, or account requirements; when they need to compare requirements between connected-account setups; or when they ask which verification fields, documents, or business details are required for a particular platform country, account country, business type, dashboard, service agreement, or capability.
stripe-pay
docs.stripe.com
Helps users send funds to another Stripe business, transfer money to a Stripe Profile handle or network ID, or ask whether an agent can pay a Stripe business. Use Stripe Directory to find or verify a recipient when the user doesn't provide an exact Stripe Profile handle or network ID.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.