Billing Migration Template for Product Planning

A big-bang migration (all customers at once) works when your subscriber count is under 500 and your billing logic is simple (one or two plans, no complex add-ons). Rolling cohort migration is safer for larger customer bases because it limits blast radius. If cohort 1 reveals a data mapping error, you fix it before cohort 2 instead of affecting every customer simultaneously. For more on managing phased rollouts, see the [glossary entry on feature flags](/glossary/feature-flag).

Calculate the remaining trial days in the old system and set the `trial_end` date in the new system to match. Run a reconciliation check 24 hours before migration to capture any trial conversions that happened between your data snapshot and migration execution. Customers on trial should be in an early migration cohort since they have lower financial risk if something goes wrong.

Some providers support token migration (Stripe and Braintree have bilateral agreements, for example). If token migration is not available, you have two options: ask customers to re-enter payment details (friction, but clean), or use the old provider solely for charging existing tokens while routing new customers to the new provider (complex, but frictionless). The second approach means running two systems indefinitely, which the [Product Operations Handbook](/product-ops-guide) covers in its systems management chapter.

Use your target provider's test/sandbox mode with production-shaped data. Clone your production customer database (with PII stripped), recreate all plans and prices in test mode, and run the full migration script. Then simulate a billing cycle by triggering invoice creation for every migrated subscription. Compare the test invoices against what your old system would have generated for the same period. Differences reveal mapping errors before real money is involved. ---