> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/integrations/billing-and-payments/metronome-usage-based-billing.md). # Metronome PeakCommerce integrates natively with **Metronome** as a billing provider for **usage-based and consumption billing**. It sits alongside Zuora and Stripe as a first-class billing adapter: a Metronome-backed tenant sells through the same catalog, journeys, customer portal, and admin surfaces as any other, while Metronome handles the part it specializes in — metering, rating, and finalizing invoices for consumption pricing. Watch how the pairing works — connect Metronome, link Stripe for collection, and route a journey step's commerce action straight to Metronome: {% embed url="" %} ## Why it matters Usage-based pricing — metered consumption, included allowances, overage rates, and hybrid subscription-plus-usage models — is hard to get right because it ties metering, rating, and invoicing together. Metronome provides that rating engine; PeakCommerce contributes the catalog, the buying journeys, and the customer-facing self-service experience. Together they let you package and sell consumption products without building the billing math yourself. ## The billing model: Metronome rates, Stripe collects Metronome finalizes invoices but does not collect payment itself. Instead, each Metronome customer is linked to a Stripe customer, and finalized invoices are pushed to Stripe, which charges the customer's default payment method automatically. A Metronome-backed tenant therefore runs **two integrations**: 1. A **Metronome** integration — catalog, contracts, usage, and invoicing. 2. A **Stripe** integration — card capture, saved payment methods, and payment collection. The Stripe integration is linked from the Metronome integration's settings and is **required** before the pairing can process payments. See the [Stripe integration](/integrations/billing-and-payments/stripe-payments.md) for how to connect Stripe itself. ## Connecting Metronome Navigate to **Settings → Integrations** and choose the **Metronome** card, then create an instance. The form asks for: * **Bearer Token** — a Metronome API bearer token. The field is masked like other secrets; when editing an existing integration, leave it empty to keep the stored token. * **API Base URL** — optional. Defaults to `https://api.metronome.com`. * **Environment** — Sandbox or Production. Match it to the Metronome environment the token belongs to. * **Linked Stripe integration** — the sibling Stripe integration that owns card capture and payment collection. Only active Stripe integrations appear in the list. This is required before the integration can process payments. * **Primary billing provider** — marks this integration as the tenant's primary billing provider, so commerce surfaces resolve accounts, subscriptions, and invoices through it. * **Send usage events to Metronome** — opt-in usage ingest (see [Usage ingest](#usage-ingest-optional) below). Off by default. Use the **Test Connection** button before saving: it makes a minimal read against the Metronome API, which verifies both the bearer token and the base URL in one step. ## Catalog sync Metronome models its catalog as **Products × Rate Cards**: a product carries identity (name, type, billable metric), and a rate card carries the price for each product and billing frequency. PeakCommerce's canonical catalog is three-level — **Product → Plan → Charge** — so the sync flattens the Metronome shape into it: * Each Metronome **product** becomes a PeakCommerce **product**. * Each **rate-card entry** becomes one **plan** on that product, with a single embedded **charge** mirroring the rate. * **Monthly and annual rates become distinct plans on the same product.** Metronome distinguishes them only by billing frequency on the rate card, so each frequency gets its own plan (for example "Growth — Month" and "Growth — Annual"). This matters later: switching billing frequency is a plan change, not a toggle. Supported rate shapes: * **Flat** recurring or one-time fees (subscription and fixed products). * **Per-unit** usage rates (a flat rate on a usage product prices each unit consumed). * **Tiered** rates, synced with their full tier bands. Rates marked not-entitled in Metronome sync as inactive — they exist on the rate card but are not sellable. Two honesty guarantees are built into the sync: * **Schema-invalid items surface as visible drops, never silent skips.** If a product, rate card, or rate comes back from Metronome in a shape the sync cannot safely read, it is recorded as a structured drop on the sync result — visible in [Catalog Sync History](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/settings/billing-catalog/catalog-sync-history.md) — rather than quietly disappearing from your catalog. * **Non-fiat credit types persist with a warning.** Rates denominated in a custom credit type (prepaid credits rather than currency) are synced, but carry an explicit warning and no locally modeled price — they are never silently mis-priced. Rates in Metronome's USD credit type are converted and displayed as USD. After the first sync, the catalog stays aligned through the same machinery as other billing providers — see [Catalog Drift](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/settings/billing-catalog/catalog-drift.md) and [Billing Integration Cache](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/settings/billing-catalog/billing-integration-cache.md). ## Selling through journeys A signup journey for a Metronome-backed tenant provisions across both integrations, in order: 1. **Stripe customer** — created first, so a collection path exists. 2. **Payment method** — the journey's payment block runs in **Stripe mode**: card details are captured with Stripe Elements directly on your page (there is no hosted payment page redirect), tokenized by Stripe, and attached as the customer's default payment method. 3. **Metronome customer** — created and linked to the Stripe customer for automatic collection. If the Stripe link cannot be established, provisioning fails loudly rather than creating a customer who has no way to pay. 4. **Contract** — created on the selected plan, carrying the plan's commercial terms: the **included allowance** (a recurring credit that offsets usage charges up to the plan's included amount) and any **overage rate override** (a plan-specific per-unit price that replaces the rate-card default). Prorated amounts are billed immediately. Included allowances and overage overrides are configured per plan on the Metronome integration; journey field mappings can override them per flow when needed. ## Customer portal Customers on a Metronome-backed tenant get the standard portal surfaces: * **Subscription detail** — the contract's plan, price, quantity, term dates, and status. * **Invoices** — the full invoice list with amounts, due dates, and paid/posted status. Payment status reflects collection through the linked Stripe customer. * **Usage drawdown** — a live view of the current billing period: **real usage** so far, the **included allowance**, an **overage flag** when usage has crossed the allowance, and **days remaining** in the period. The drawdown reads actual usage rather than the remaining credit balance, deliberately — a credit balance stops at zero once the allowance is burned, so it could never show usage *crossing* the allowance, which is exactly the state customers most need to see. * **Payment methods and payments** — these ride the linked Stripe customer. Adding, removing, and defaulting cards, payment history, and refunds all flow through Stripe. If a drawdown figure cannot be read live from Metronome, the entry is omitted rather than estimated — the portal never invents a number. ## Plan changes * **Base-plan swap** — committing a plan change creates a renewal-transition contract in Metronome: the new contract supersedes the old one at its start date, and Metronome handles upgrade proration. The new contract carries the target plan's allowance and overage terms, exactly as a fresh signup would. * **Quantity changes and add-ons** — applied as edits to the existing contract, with prorated amounts billed immediately. * **Billing-frequency changes are plan changes.** Because monthly and annual rates sync as separate plans, moving a customer from monthly to annual billing goes through the change-plan flow, not a frequency toggle. * **No live billing preview.** Metronome does not expose a preview API for contract changes, so the order summary shown before commit is a **modeled estimate** computed from the synced rates — not a provider-calculated invoice preview. The final invoice comes from Metronome's own rating at collection time. ## Retention and cancellation * **Retention discounts** — percentage retention offers apply as bounded overrides on the contract's subscription product. Because the override is a true percentage multiplier, the discount tracks any rate change during its window, and the window itself is bounded by the offer's configured duration (for example, three billing cycles). Only **percentage** discounts are supported; fixed-amount retention discounts are not available on Metronome. * **Cancellation** — cancelling moves the contract's end date to the **end of the current billing period**, so the customer keeps access to what they paid for until the period closes. An explicit effective date, where a flow supplies one, takes precedence. ## Usage ingest (optional) Off by default, the **Send usage events to Metronome** switch streams PeakCommerce's own commerce activity to Metronome as usage: when an order completes, its executed commerce value is emitted as a usage event against the tenant's Metronome customer. This is for pricing models where the metered quantity *is* commerce executed through the platform. The emitter is built to never mis-bill: * **Idempotent per order** — each event carries a deterministic transaction ID derived from the order, so Metronome deduplicates retries and a re-emitted order can never double-bill. * **Only completed orders count** — failed, cancelled, and reversed orders are never emitted. * **USD only in v1** — orders in other currencies are skipped with a visible warning rather than converted at a guessed rate. * **Never blocking, never silent** — emission happens after the order commits and never blocks or fails the buyer's checkout; every skipped or failed emission is logged visibly, and every API attempt is recorded in API Call Stats. ## Not supported yet Stated plainly, so you can plan around it: * **Invoice PDF download and invoice email** — not available; the portal hides the affordances. * **Credit memos** — not surfaced. * **Plan-change preview** — no provider-side preview; the portal shows a modeled estimate (see [Plan changes](#plan-changes)). * **Pause / suspend** — not modeled on Metronome contracts. * **Fixed-amount retention discounts** — percentage offers only. * **Contact and address edits** — customer contact identity lives on the linked Stripe customer; edit it there, not on the Metronome side. * **Audience rules on provider fields** — Metronome exposes no field-query surface, so audience conditions cannot match against Metronome account data. ## Gotchas * The **Linked Stripe integration is not optional** in practice: a Metronome customer without a Stripe link has no way to pay. Connect and verify Stripe first. * Usage-based billing is only as correct as the usage you emit — validate metering end-to-end in a sandbox environment before going live. * Because monthly and annual are distinct plans, make sure both frequencies you intend to sell exist on the rate card before syncing; a missing frequency simply won't have a plan to sell. ## See also * [Stripe integration](/integrations/billing-and-payments/stripe-payments.md) — the linked payment side of a Metronome pairing. * [Billing & Payments integrations](/integrations/billing-and-payments/billing-and-payments.md) * [Integrating billing systems with PeakCommerce](/integrations/billing-and-payments/integrating-billing-systems-with-peakcommerce.md) * [Zuora billing integration](/integrations/billing-and-payments/zuora-integration/zuora-billing-integration.md) * [Catalog Sync History](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/settings/billing-catalog/catalog-sync-history.md) * [Catalog Drift](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/settings/billing-catalog/catalog-drift.md) * [Billing Integration Cache](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/settings/billing-catalog/billing-integration-cache.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.peakcommerce.com/integrations/billing-and-payments/metronome-usage-based-billing.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.