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:

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:

A Metronome integration — catalog, contracts, usage, and invoicing.
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 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 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 — 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 and Billing Integration Cache.

Selling through journeys

A signup journey for a Metronome-backed tenant provisions across both integrations, in order:

Stripe customer — created first, so a collection path exists.
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.
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.
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).
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.