# Migrate existing customers

Move your current customers from basic usage-based billing to Metronome.

Migrate existing Stripe basic usage-based billing customers to Metronome. The steps vary slightly depending on whether you’re doing a hard cutover or a parallel run, and how your billing periods are aligned.

## Preparation

1. Create Metronome customers with `stripe_customer_id` linked, and set ingest aliases so your engineering team can send events using your internal customer ID instead of Metronome’s UUID.
2. Set customers as unbillable in Metronome using the `setBillableStatus` endpoint.
3. Set Stripe billing provider configuration on each Metronome customer.

To learn more, see [Set billing provider configurations](https://docs.metronome.com/api-reference/customers/set-billing-provider-configurations-for-a-customer).

## Create contracts

Create contracts for each customer:

1. Point to your standard rate card.
2. Set the contract start date to the date the customer started their subscription in Stripe.
3. Set invoice generation to begin at the parallel run start.
4. Include any credits or commits migrated from Stripe Credit Grants.
5. Set the contract billing provider to the Stripe configuration from when you configured customers in the preparation step.

To learn more, see [Create a contract](https://docs.metronome.com/api-reference/contracts/create-a-contract#create-a-contract).

## Run your migration

Choose a migration strategy. The safest option we recommend is the month-boundary parallel run.

#### Parallel run (recommended)

1. Send usage events to both Stripe and Metronome.

   Stripe subscriptions remain active and Stripe continues to invoice customers normally. Metronome generates unbillable invoices for parity validation only — these are not sent to Stripe.

2. Run parity checks comparing Stripe invoice totals versus Metronome invoice totals.

   To learn more, see [Test and deploy](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/test-and-deploy.md#parallel-run-parity-checks).

> #### Common mistake
> 
> If you see usage in Metronome (under **Connections**) but no charges on the invoice, verify that your events’ property values match the pricing group key values configured on your rate card. This is the most common setup issue.

#### Hard cutover

1. End Stripe subscriptions at the end of the current billing period (for example, end of January):

   - Use subscription schedules to cancel at period end, OR
   - Update subscriptions with `cancel_at_period_end: true` using `POST /v1/subscriptions/{id}`

2. Schedule customers as billable in Metronome effective at the start of the next period (for example, February 1st).

3. Stop sending events to Stripe and redirect exclusively to Metronome.

   From February onward, invoices come exclusively from Metronome and are pushed to Stripe for payment collection.

## Post-migration clean up

1. Remove Stripe Meter configurations (or leave dormant).
2. Archive unused Stripe Prices.
3. Flip feature flags for dashboards, alerting, and reporting.
4. Decommission the dual-write event pipeline.

## Migrate active Stripe Credit Grants

If customers have active Stripe Credit Grants, you must manually recreate them in Metronome because they aren’t automatically transferred. The Credit Grant object only stores the original amount, not the remaining balance. Retrieve remaining balances using [GET /v1/billing/credit_balance_summary](https://docs.stripe.com/api/billing/credit-balance-summary.md) before you proceed.

**Before cutover**, use Metronome’s API to create equivalent commits or credits on the contract:

- Use the **remaining balance** (not the original amount)

- Match priority, expiration, and applicability

- Map grant categories as follows:

| Stripe category | Metronome equivalent                        |
| --------------- | ------------------------------------------- |
| `paid`          | Prepaid Commit (has invoice schedule)       |
| `promotional`   | Credit (complimentary, no invoice schedule) |

**At cutover**. Stripe stops drawing down the Credit Grant because it no longer generates usage invoices. **Post-cutover**, Metronome draws down credits on the contract against Metronome invoices.

## Optional: Migrate threshold billing or auto-recharge

If you use Stripe’s threshold billing:

1. Create the Metronome contract without auto-recharge enabled.
2. Complete your [parallel run and parity validation](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/migrate-existing-customers.md#run-migration).
3. At cutover:
   1. End the Stripe subscription.
   2. Migrate the remaining credit balance to a Metronome commit.
   3. Enable auto-recharge on the Metronome contract.
   4. Set the customer as billable.

> Metronome ignores the unbillable status when auto-recharge is enabled on the contract. Only enable auto-recharge after you’re ready to go live.

## Next steps

After you migrate your existing customers, [test and deploy](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/test-and-deploy.md).