# Test and deploy

Validate your Metronome migration and deploy to production.

Validate your integration in sandbox, then run a production parallel comparison before cutover. Then deploy and monitor your first billing cycle.

## Before you begin

1. [If you don’t have a Metronome account, sign up for a sandbox](https://signup.metronome.com/).
2. [Set up your billing model](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/set-up.md).
3. [Migrate existing customers to Metronome](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/migrate-existing-customers.md).

## Test

1. Set up product catalog in Metronome’s sandbox or test environment (billable metrics, then products, then rate cards)

2. Configure Stripe test mode integration in Metronome

3. Test event ingestion. Send test meter events and verify they appear in Metronome

   - In sandbox, you can send test events directly from the Metronome UI: navigate to a customer’s contract view, click a product on the rate card, and use the test event sender
   - Make sure `transaction_id` is unique per event, `timestamp` is within the last 34 days, and `event_type` and properties match your billable metric’s configuration

4. Test invoice generation. Verify draft invoices are correctly created with expected line items

   - Navigate to **Customers** > **Contract** > **Invoices** to see the draft invoice.

5. Test Stripe sync. Verify invoices appear in Stripe test mode with correct totals after the 24-hour grace period and finalization

6. Test credit drawdown. Verify commits or credits draw down correctly against usage in the expected priority order

7. Test dashboards and alerting. Verify customer-facing and internal tools.

Use Stripe’s [Test Clocks](https://docs.stripe.com/billing/testing/test-clocks.md) to simulate time progression for Stripe-side invoice processing and payment collection during testing. Test Clocks support Subscriptions and Invoices but might not simulate Billing Meter aggregation.

> #### Common mistake
> 
> If you see usage (under Connections) but no charges on the invoice, check that your events’ property values match the pricing group key values defined on your rate card. For example, if your rate card has rates for `model_name` = “gpt-4” but your events send `model_name` = “GPT-4”, the usage isn’t rated.

## Parallel run parity checks

During your production parallel run, automate these validations:

| Check                        | How                                                                                          |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| Invoice totals match         | Compare Stripe invoice total versus Metronome invoice total for the same customer and period |
| Line item quantities match   | Compare metered quantities on both invoices                                                  |
| Credit application matches   | Compare credit drawdown amounts                                                              |
| All customers have contracts | Verify every active Stripe subscription customer has a corresponding Metronome contract      |
| Event ingestion parity       | Compare Stripe Meter Event Summaries versus Metronome usage aggregations                     |
| Group key coverage           | Verify all dimension values in events have corresponding rates on the rate card              |

## Smoke test checklist

- [ ] New customer creation flow works end-to-end
- [ ] Ingest aliases resolve correctly (events sent with internal ID appear on correct customer)
- [ ] Usage events are ingested and aggregated correctly
- [ ] Invoice finalization produces correct totals (after 24-hour grace period)
- [ ] Invoices appear in Stripe with correct line items
- [ ] Payments are processed successfully
- [ ] Credits and commits draw down in correct priority order (rollover commits, then prepaid commits and credits, then post-paid commits, then by priority within each type)
- [ ] Quantity conversions display correctly (for example, tokens to millions of tokens)
- [ ] Alerts fire at configured thresholds
- [ ] Embeddable or custom dashboards show correct data
- [ ] Data export delivers expected datasets
- [ ] Webhook delivery is reliable for invoice and payment events

## Deploy

Execute the production cutover and monitor the first billing cycle.

### Cutover checklist

- [ ] Parallel run completed with acceptable parity (recommend <1% variance)
- [ ] All active subscriptions scheduled for end-of-period cancellation
- [ ] All customers scheduled to become billable at period start
- [ ] Event pipeline redirected exclusively to Metronome
- [ ] Auto-recharge enabled on contracts that need it (only after billable status is set)
- [ ] Feature flags ready for dashboard, alerting, and reporting switchover
- [ ] Runbook prepared for rollback if issues discovered
- [ ] Customer communication sent (if invoice format or branding changes)

### Post-cutover monitoring

1. Monitor Metronome webhook delivery for invoice and payment events.
2. Monitor Stripe for payment failures on Metronome-pushed invoices.
3. Validate first full billing cycle invoice totals against historical baselines.
4. Listen for `invoice.billing_provider_error` webhooks from Metronome (indicates Stripe sync issues).
5. Verify the 24-hour grace period timing aligns with your late-arriving event patterns.
6. Check that all pricing group key values are covered (missing rates = unbilled usage).

### Rollback plan

If critical issues are discovered post-cutover:

1. Set affected customers back to unbillable in Metronome.
2. Recreate Stripe subscriptions (or reactivate if not yet fully canceled).
3. Resume sending events to Stripe.
4. Investigate and resolve issues before re-attempting.