# Set up Metronome

Configure your pricing and billing model in Metronome.

Set up your billing model in Metronome to match or extend your existing basic usage-based billing configuration.

## Before you begin

1. [Scope your migration](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/scope-your-migration.md).
2. [Design your migration](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/design-your-migration.md).

## Configure your Metronome product catalog

You must create objects in this sequence: Billable Metrics, Products, Rate Cards, Customers, Contracts. Each object depends on the previous.

### Create billable metrics

Create billable metrics in Metronome that match your Stripe Meter configurations:

1. Name your metric (for example, “Input Tokens”).

2. Set the event type filter. This must exactly match the `event_type` your application sends.

3. Define properties. Include all properties you might want to aggregate or group.

4. Choose your aggregation type (SUM, COUNT, MAX, or LATEST).

5. Define group keys. Include all properties you might want to price by or display on invoices.

   > You can’t modify group keys, aggregation type, and event type filter after creation. Include more group keys than you think you need. You can always ignore them, but can’t add them later. Avoid high-cardinality properties (like `request_id`) as group keys. Contact Metronome if cardinality approaches 1,000.

After creation, Metronome shows an example event payload in the UI that shows the expected format. Use this to validate your event instrumentation.

To learn more, see [Create a billable metric](https://docs.metronome.com/api-reference/billable-metrics/create-a-billable-metric).

### Create products

Create one Product per billable SKU/item:

1. Enter a **Name** (this appears on the invoice).

2. Select **Product Type**: Usage, Subscription, Composite, or Fixed.

3. For Usage products, select the billable metric you created.

4. Assign **Group keys**:

   - **Pricing group key**: Different prices per dimension value
   - **Presentation group key**: Invoice line-item breakdowns (same price)
   - Use both if needed: For example, price by `model_name`, display by `user_id`.

5. *(Optional)* Add quantity conversions (for example, tokens to millions of tokens) or rounding conversions (for example, seconds to minutes).

To learn more, see [Create Product](https://docs.metronome.com/api-reference/products/create-a-product).

### Create rate cards

Create a [Rate Card](https://docs.metronome.com/guides/get-started/how-metronome-works#rate-cards) with rates for each product:

1. Name your rate card (for example, “Standard Rate Card”)
2. Add products and set their rates
3. If using dimensional pricing, define values for each dimension and set a rate per value
4. *(Optional)* Configure tiered pricing, custom pricing units, or commit-specific rates

To learn more see, [Create Rate Card](https://docs.metronome.com/api-reference/rate-cards/create-a-rate-card).

## Connect Metronome to Stripe

Configure the Metronome to Stripe invoicing integration:

1. Connect your Stripe account in the Metronome Dashboard ([General Settings](https://app.metronome.com/settings/general) > [Integrations](https://app.metronome.com/settings/general/integrations)).
2. [Configure entity mappings if you have multiple Stripe entities](https://docs.metronome.com/integrations/invoice-integrations/stripe#connecting-metronome-to-multiple-stripe-accounts)
3. [Set collection method preferences (per-customer or account-level)](https://docs.metronome.com/integrations/invoice-integrations/stripe#set-the-customer-billing-configuration)

To learn more see, [Invoice with Stripe](https://docs.metronome.com/integrations/invoice-integrations/stripe).

## Set up event ingestion

Redirect your usage event pipeline to send events to both Stripe and Metronome during the parallel run period.

**Stripe basic usage-based billing event format**:

```json
{
  "event_name": "api_requests",
  "payload": {
    "stripe_customer_id": "cus_xxx",
    "value": "1",
    "region": "us-east-1"
  },
  "timestamp": 1700000000
}
```

**Metronome event format**:

```json
{
  "transaction_id": "unique-event-id-123",
  "customer_id": "metronome-customer-id",
  "event_type": "api_requests",
  "timestamp": "2024-01-15T10:00:00Z",
  "properties": {
    "region": "us-east-1",
    "value": 1
  }
}
```

### Key differences

| Field          | Stripe                         | Metronome                                                |
| -------------- | ------------------------------ | -------------------------------------------------------- |
| Deduplication  | Auto-generated if not provided | Required `transaction_id` (must be unique per event)     |
| Customer ID    | `stripe_customer_id`           | Metronome UUID or ingest alias (your internal ID)        |
| Timestamp      | Unix timestamp (integer)       | RFC 3339 (for example, `2024-01-15T10:00:00Z`)           |
| Properties     | Values as strings              | Typed (numbers as numbers, not strings)                  |
| Property limit | Limited                        | Rich property payloads supported                         |
| Event type     | `event_name`                   | `event_type` (must exactly match billable metric filter) |

Use Metronome’s ingest aliases to send events using your internal customer ID instead of Metronome’s UUID. Set these when creating customers.

To learn more, see [Metronome Ingest API](https://docs.metronome.com/api-reference/usage/ingest-events) and [Design Usage Event](https://docs.metronome.com/guides/events/design-usage-events).

## Configure new customers in Metronome

Configure new customers on Metronome before you migrate legacy customers from your existing basic usage-based billing integration. This helps validate your end-to-end integration with lower risk.

For each Stripe customer you migrate:

1. [Create a customer](https://docs.metronome.com/guides/customers-billing/manage-customers/provision-a-customer) in Metronome.
2. (Recommended) Set [ingest aliases](https://docs.metronome.com/guides/customers-billing/manage-customers/provision-a-customer#understand-ingest-aliases) so your engineering team can send events using your internal customer ID instead of Metronome’s UUID.
3. Set the Stripe Customer ID on the Metronome customer to link invoicing.
4. Once you’re ready to go live and start billing customers, set the [customer billing provider configuration to Stripe](https://docs.metronome.com/integrations/invoice-integrations/stripe#set-the-customer-billing-configuration).
   - Don’t set the customer billing provider until you stop using Stripe usage-based billing to bill customers. This prevents customers from being double-charged in both Stripe usage-based billing and Metronome.

To learn more, see [Customers and billing](https://docs.metronome.com/guides/customers-billing/overview).

## Create contracts

[Create a contract](https://docs.metronome.com/guides/get-started/metronome-dashboard-quickstart#create-a-contract) for each customer:

1. Select your rate card.

2. Set the contract start date and end date.

3. Configure billing provider (Stripe) with the configuration from when you created the customer.

4. *(Optional)* Include customer-specific terms:

   - [Prepaid commits](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/create-a-pre-paid-commit#prepaid-commits) or [credits](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/create-a-pre-paid-commit#grant-a-free-credit) (migrated from Stripe Credit Grants)
   - [Overrides](https://docs.metronome.com/guides/pricing-packaging/make-pricing-changes/edit-or-override-a-contract#override-types) (customer-specific pricing that differs from the rate card)
   - [Discounts](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/discounting-on-commits#offer-discounts-on-commits)

For [self-serve and PLG flows](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md#self-serve-and-plg-models): Consider using Metronome [Packages](https://docs.metronome.com/guides/implement-metronome/core-concepts/packages-overview) to encode your standard rate card and contract details into a reusable template you can apply programmatically across many customers. To learn more, see [Create a package](https://docs.metronome.com/guides/implement-metronome/core-concepts/packages-overview#create-a-package).

To learn more, see [Create a contract](https://docs.metronome.com/api-reference/contracts/create-a-contract) and [Provision a customer contract](https://docs.metronome.com/guides/implement-metronome/core-concepts/provision-contract).

## Migrate Credit Grants

Complete the steps in [Migrate existing customers](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/migrate-existing-customers.md#migrate-credit-grants).

## Configure alerts

1. [Set up Metronome alerts](https://docs.metronome.com/guides/customers-billing/set-up-notifications/create-and-manage-notifications) (spend thresholds, balance alerts) to replace any Stripe webhook-driven workflows.
2. [Configure Metronome webhook endpoints for your systems](https://docs.metronome.com/guides/platform-configuration/setup-webhooks).
3. Make sure your system can differentiate between Stripe-originated webhooks (for existing subscriptions) and Metronome-originated events during the parallel run.
4. Set up webhooks for payment statuses if using payment-gated commits.

## Update dashboards and reporting

Set up a customer dashboard. Choose any of the following based on your use case:

- [Embeddable Dashboards](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/customer-dashboards-and-reporting#embeddable-dashboards): Metronome offers several API endpoints that provide data useful for powering dashboards that your customers want to see. To get started with Metronome Embeddable Dashboards, see [Use Metronome APIs to power customer-facing dashboards](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/customer-dashboards-and-reporting#use-metronome-apis-to-power-customer-facing-dashboards).
- [Data Export](https://docs.metronome.com/guides/reporting-insights/data-export/overview): Enable Metronome data export objects and integrate into your reporting pipeline.

To learn more, see [Build API-powered customer dashboards](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/customer-dashboards-and-reporting#embeddable-dashboards).

## Next steps

- [Migrate existing customers to Metronome](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/migrate-existing-customers.md)
- [Test and deploy](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/test-and-deploy.md)