# Design your migration

Map your Stripe billing objects to Metronome's architecture, design your product catalogue and choose an integration pattern.

Before migrating your existing customers to Metronome, design your migration:

1. Map your Stripe billing objects to Metronome’s architecture.
2. Design your product catalogue.
3. Choose an integration pattern.

## Before you begin

If you haven’t already, [scope your migration](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/scope-your-migration.md).

## Mapping between Stripe and Metronome concepts

Familiarise yourself with Metronome’s core objects and how they correspond to Stripe’s usage-based billing concepts.

### Metronome’s core objects

Metronome separates metering (what you measure) from rating (what you charge). This means you can update pricing without changing your event instrumentation, and vice versa.

Metronome’s object hierarchy: Usage Events > Billable Metrics > Products > Rate Cards > Contracts > Invoices.

| Concept              | Description                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Usage Events**     | Raw records of customer activity (e.g. “customer X used 1,500 input tokens on model gpt-5”)                                                  |
| **Billable Metrics** | Rules that aggregate events into billable quantities. Also where you define group keys (properties used to price by or display on invoices)  |
| **Products**         | Named line items on an invoice. Have a 1:1 relationship with Billable Metrics for usage products                                             |
| **Rate Cards**       | A centralised price book assigning a price to each product. A single rate card can be shared across many customers                           |
| **Contracts**        | Customer-specific agreements referencing a rate card, defining the billing period and optionally including credits, commits or overrides     |
| **Packages**         | Encode your rate card and contract details in a single reusable package to be applied across new customers (useful for PLG/self-serve flows) |
| **Invoices**         | Generated automatically each billing period based on usage, rated against the contract                                                       |

### Compare Stripe and Metronome’s billing concepts

| Stripe basic usage-based billing concept                                       | Metronome concept                                                                                                       | Description                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Billing Meter](https://docs.stripe.com/api/billing/meter/object.md)           | [Billable Metric](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-billable-metrics)          | Both define aggregation rules. Streaming metrics support SUM, COUNT, MAX and LATEST. SQL metrics additionally support UNIQUE (count distinct). Compound group keys enable dimensional pricing. Group keys, aggregation type and event type filter can’t be modified after creation. |
| [Meter Event](https://docs.stripe.com/api/billing/meter-event/create.md)       | [Usage Event (Ingest)](https://docs.metronome.com/api-reference/usage/ingest-events)                                    | Both represent individual usage records. Metronome events include a `transaction_id` for deduplication and support rich property payloads.                                                                                                                                          |
| [Price (usage-based)](https://docs.stripe.com/api/prices.md)                   | [Rate (on a Rate Card)](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-manage-rate-cards)   | A Stripe Price defines unit cost and meter linkage. In Metronome, a Rate defines pricing for a Product on a Rate Card. Supports tiered pricing, dimensional pricing and commit-specific rates.                                                                                      |
| [Product](https://docs.stripe.com/api/products.md)                             | [Product](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts)                | In Stripe, Products group Prices. In Metronome, Products have a 1:1 relationship with Billable Metrics. Product types: Usage, Subscription (recurring fee), Composite (% charge on other products), Fixed (one-time/scheduled).                                                     |
| [Subscription](https://docs.stripe.com/api/subscriptions.md)                   | [Contract](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts)               | A Metronome Contract is more powerful. It includes rate card references, commits, credits, discounts, overrides and schedules.                                                                                                                                                      |
| [Credit Grant](https://docs.stripe.com/api/billing/credit-grant/object.md)     | [Prepaid Commit or Credit](https://docs.metronome.com/api-reference/contracts/create-a-contract)                        | Commits have an invoice schedule (customer pays upfront or at expiry); Credits are complimentary (no invoice schedule). Both support priority, expiry and scoped applicability on a Contract.                                                                                       |
| [Subscription Schedule](https://docs.stripe.com/api/subscription_schedules.md) | [Contract amendments and scheduling](https://docs.metronome.com/guides/implement-metronome/migrate-amendments-to-edits) | Metronome supports in-contract scheduling of pricing changes, renewals and amendments natively.                                                                                                                                                                                     |
| [Invoice](https://docs.stripe.com/api/invoices/object.md)                      | [Invoice](https://docs.metronome.com/guides/invoices/overview)                                                          | Metronome generates invoices and pushes them to Stripe for payment collection. Default 24-hour grace period after billing period end before finalisation.                                                                                                                           |

For more information, see [How Metronome works with Stripe](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md).

## Design your product catalogue

Use your existing Stripe Meters, Prices and Products as a starting point for designing your Metronome product catalogue. The sections below walk through each object type.

### Billable metrics

Metronome offers two types of billable metrics:

- **Streaming Metrics** (recommended): Aggregates events in real time as they arrive. Use this for most use cases.
- **SQL Metrics**: For complex calculations such as daily averages, unique counts per period or weighted formulas. Use SQL metrics only if streaming metrics cannot support your requirements.

Design principles:

- **If you use Stripe meter segments**: Evaluate whether Metronome’s dimensional pricing (compound group keys) lets you consolidate multiple Stripe Meters into fewer Metronome Billable Metrics.
- **If you don’t use segments**: Your Metronome Billable Metrics will likely map 1:1 from your existing Stripe Meters with the same aggregation type.
- **Cardinality**: Contact your Metronome representative if a group key’s cardinality approaches 1,000. Avoid adding high-cardinality properties (such as request_id or unbounded IDs) as group keys.

> You can’t change group keys, aggregation type and event type filter after creation. Plan these carefully before saving your billable metric.
> 
> Include more group keys than you think you need. You can always ignore unused group keys, but you can’t retroactively add them. If you might want to price by or display a dimension in the future, include it as a group key now.

### Aggregation type mapping (streaming metrics)

| Stripe            | Metronome | Description                               |
| ----------------- | --------- | ----------------------------------------- |
| SUM               | SUM       | Sums a numeric property across events     |
| COUNT             | COUNT     | Counts matching events                    |
| LAST              | LATEST    | Takes the most recent value in the window |
| MAX (legacy only) | MAX       | Maximum value in a window                 |

### SQL metrics

For UNIQUE (count distinct) aggregation, use a [SQL billable metric](https://docs.metronome.com/guides/implement-metronome/core-concepts/billable-metrics-sql-editor).

### Group keys

Group keys determine what you can price by and how usage is broken down on invoices. Think of them like a `GROUP BY` clause in SQL, where they split aggregated usage into buckets based on a property value.

Group keys enable the following downstream configurations on a Product:

| Downstream use         | What it does                              | Example                                                         |
| ---------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| Pricing group key      | Different prices per dimension value      | `model_name` -> charge US$1.50 for model-A, US$0.30 for model-B |
| Presentation group key | Invoice line-item breakdowns (same price) | `user_id` -> show per-user usage on invoice                     |

Common group key examples:

- `model_name`: Per-model pricing (pricing group key)
- `region`: Per-region pricing (pricing group key)
- `instance_type`: Per-GPU/instance pricing (pricing group key)
- `user_id` : Per-user invoice breakdowns or seat-based billing using Unique aggregation (presentation group key)
- `project_id`: Per-project invoice breakdowns (presentation group key)

Review your Stripe meter segment dimensions. These are your primary candidates for Metronome group keys. Also consider additional properties in your event payload that you’re not currently using for segmentation but might want for future pricing flexibility or invoice presentation.

### Products

Metronome Products represent individual service offerings:

| Type         | Use case                                                           | Stripe equivalent |
| ------------ | ------------------------------------------------------------------ | ----------------- |
| Usage        | Variable pricing based on consumption (requires a billable metric) | Usage-based Price |
| Subscription | Recurring fee on a schedule (platform fees, seat licences)         | Recurring Price   |
| Composite    | Percentage charge on a group of other products                     | –                 |
| Fixed        | One-time or scheduled charges (used for commits and credits)       | –                 |

Key configuration options on Products:

- **Group keys**: Assign pricing group keys (different prices per dimension) or presentation group keys (invoice breakdowns). These must be a subset of the group keys defined on the billable metric.
- **Quantity conversion**: For example, send individual tokens but display and price per million tokens on the invoice.
- **Rounding conversion**: For example, send seconds but round to the nearest minute on the invoice.

### Rate cards

A Rate Card is a centralised pricing template that contains rates for all your Products. Each rate card is denominated in a single fiat currency. Create a single rate card as your standard pricing source of truth. When you update rates on a rate card, the changes propagate to all contracts that reference it. Manage custom pricing for specific customers through overrides on individual contracts.

Rate card features:

- **Dimensional pricing**: If using pricing group keys, define rates per dimension value (for example, model-A at US$1.50, model-B at US$0.30).
- **Tiered pricing**: Set volume-based tiers on any product (for example, first 1M tokens at US$1.00, next 1M at US$0.80).
- **Custom Pricing Units**: If you bill in credits or a custom unit rather than fiat currency, create a Custom Pricing Unit under Offering then Pricing Units and configure the conversion on the rate card.
- **Commit rates**: Set rates that apply specifically when usage draws down from a commit.
- **Rate changes**: Edit rates with a start date for the new rate; changes propagate to referencing contracts.

### Invoicing

Metronome’s [invoice lifecycle](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md) follows these steps:

1. **Draft**: Accumulates usage throughout the billing period (viewable in Metronome).
2. **Grace period**: 24-hour window (default) at the end of the billing period before finalisation, allowing late-arriving usage data and corrections.
3. **Finalised**: Metronome locks the invoice after the grace period; no further changes allowed.
4. **Sent to billing provider**: Metronome pushes finalised invoices to Stripe (creates `InvoiceItem` objects and an `Invoice` on the Stripe Customer).
5. **Paid or failed**: Stripe handles collection (Smart Retries, Radar and retry settings apply automatically).

Key considerations:

- Stripe Tax, Anrok or Avalara can be applied at Stripe invoice finalisation.
- Configure collection method (`charge_automatically` or `send_invoice`) per customer.
- Manage payment status in the Stripe Dashboard, not in Metronome.
- Set up webhooks to listen to payment statuses for payment-gated commits.

## Choose an integration pattern

Metronome supports the following [integration patterns](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md) with Stripe:

- **Metronome independently**: Metronome handles all billing and metering, pushes finalised invoices to Stripe for payment collection. Best if you’re fully migrating away from Stripe Subscriptions.

  **Choose Metronome independently if:**

  - All your billing is usage-based
  - You want Metronome’s full contract and commit functionality
  - You don’t need Stripe Checkout or Payment Links for signup

- **Metronome with Stripe Subscriptions**: Stripe Subscriptions handles recurring and flat-rate billing; Metronome handles usage-based metering and invoicing separately. Both create invoices on the same Stripe Customer.

  **Choose Metronome with Stripe Subscription if:**

  - You have flat-rate or seat-based recurring charges on Stripe Subscriptions
  - You want to keep Checkout, Customer Portal and Payment Links for non-usage billing
  - You only need Metronome for the usage-based component

## Next steps

After you scope and design your migration, [set up Metronome](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/set-up.md).