Stripe To Metronome Migration

This skill covers migrating from Stripe's Usage-Based Billing (Billing Meters, Prices, Subscriptions, Credit Grants) to Metronome. For general Metronome integration guidance not specific to migration, use the metronome-best-practices skill instead.

Migration routing

Read the relevant reference file before answering any migration question or generating migration code.

Critical rules

• Always set migrating customers as unbillable before creating contracts. This prevents double-billing during the parallel run period.
• Always use a parallel run (minimum one full billing cycle) before cutting over legacy customers. Compare Stripe and Metronome invoice totals to validate parity.
• Always align cutover to a billing period boundary (typically month start). Mid-period cutovers create partial billing gaps or overlaps.
• Always migrate credit grant remaining balances, not original amounts. Use GET /v1/billing/credit_balance_summary to retrieve remaining balances from Stripe.
• Never enable auto-recharge on Metronome contracts during the parallel run. Auto-recharge ignores unbillable status and will generate real charges.
• Never send events with string-typed numeric values to Metronome. Stripe accepts "value": "1" (string); Metronome requires "value": 1 (number).
• Never modify group keys, aggregation type, or event type filter after creating a billable metric. These are immutable — plan carefully upfront and include more group keys than you think you need.
• Never skip the 24-hour grace period in production. Late-arriving events after the grace period expires are lost from that billing period.

Key documentation