September 8, 2026
Data migration
Data migration is the process a subscription business uses to move its existing customer, billing, and subscription data out of a legacy system and into a new platform, so that accounts, subscriptions, and payment details remain intact and keep billing without interruption.
In a subscription business, data migration is rarely a simple copy. The source and destination model subscriptions differently, so records have to be mapped and validated as they move: customer accounts, active and cancelled subscriptions, and the stored payment methods that keep recurring charges running. Because that last category includes sensitive cardholder data, the transfer has to be handled in a PCI-compliant way. On gateways that support it, such as Stripe, Braintree, and Adyen, a merchant can migrate using gateway tokens so subscribers keep billing on the existing gateway without interruption. Moving full PCI cardholder data has no self-managed path; it requires Recurly's Professional Services team, since the sensitive nature of that data rules out a do-it-yourself transfer.
Recurly supports both self-managed migration through its API and fully managed migration handled by Recurly's Professional Services team. A subscription's billing record also carries a network transaction identifier (NTID) that has to move with it. A merchant can only migrate this value on their own after asking support to enable a feature flag and then passing a hidden parameter on subscription creation; Recurly's Professional Services team migrates NTIDs directly as part of its managed service.
Why data migration matters for subscription businesses
A subscription business runs on its billing data, so moving that data is one of the highest-stakes projects it will take on. If accounts, subscriptions, or renewal dates come across wrong, the very next billing cycle charges the wrong amount, on the wrong day, or not at all, and the damage shows up as failed payments, involuntary churn, and refunds. Migration sits upstream of almost everything else: Invoicing depends on subscriptions landing correctly, Dunning depends on stored payment methods transferring intact, and because most migrations do not carry invoice and payment history into the new platform, Revenue recognition has to be planned for separately, since the new system will not have that record to draw on.
A clean migration is also what lets a business actually switch platforms at all, since payment credentials that cannot move in a PCI-compliant way would otherwise force every customer to re-enter their card.
How to plan a data migration
A migration's job is to land the same subscription relationships in the new platform that existed in the old one, with nothing silently dropped or changed. A staged plan keeps that verifiable at each step.
Inventory and scope: list every data type that has to move, including customer accounts, subscriptions, coupons, and stored payment methods (including NTIDs tied to each billing record), and decide what stays behind at the source, such as historical invoices and payment history.
Map the models: match each field in the source system to its equivalent in the destination, and decide how to handle anything that does not map cleanly, such as custom fields, statuses, or billing rules that behave differently.
Clean the source data: resolve duplicates, dead accounts, malformed records, and inconsistent statuses before they move, so the migration does not carry old problems into the new platform.
Arrange the PCI-compliant transfer of payment methods: coordinate the secure movement of stored card and bank credentials between providers, since this is the piece that cannot be exported and re-imported by hand.
Run a test migration: load a representative subset into a sandbox or test site, then reconcile it against the source to confirm counts, amounts, and renewal dates match.
Reconcile and validate: compare the full migrated set against the source for record counts, active subscription totals, and next-billing dates, and investigate every discrepancy before go-live.
Cut over and monitor: choose whether to move all at once or in phases, freeze changes at the source during the switch, then watch the first billing cycles closely for unexpected declines or misfires.
Common mistakes with data migration
Migrating dirty data as-is, so duplicate accounts, cancelled subscriptions marked active, and stale records land in the new platform and start generating wrong invoices.
Skipping or under-scoping the test migration, then discovering mapping errors only after real customers have been billed incorrectly on the live platform.
Not planning the PCI-compliant transfer of stored payment methods early, which forces a scramble at the end or pushes customers to re-enter their cards and drives avoidable churn.
Mishandling in-flight billing state, such as proration, trial periods, or the next renewal date, so subscriptions resume on the wrong day or at the wrong amount after cutover.
Reconciling by spot check instead of by full counts and totals, which lets silently dropped records slip through unnoticed until they surface as missed charges.
Benefits and examples
Lets a business move to a platform that fits its needs without asking most customers to re-enter payment details, because credentials transfer in a PCI-compliant way or, on supported gateways, through gateway tokens.
Preserves billing continuity, so subscriptions renew on schedule and revenue keeps flowing across the switch.
Offers a choice of approach: self-managed migration through the API, whose main advantage is speed for a team that wants to move on its own timeline, or fully managed migration where Recurly's Professional Services team works closely with the merchant to pull and map the data, then runs the transfer itself. That managed process also silences customer email communications during cutover, carries NTIDs across, and marks migrated records as imported so they reconcile cleanly in revenue recognition.
Gives a business the chance to adopt Recurly features it may not have had before, such as ramp pricing, Account Updater, or intelligent retries for failed payments.
Surfaces and cleans up years of accumulated data problems in the process, so the new platform starts from a cleaner base than the old one ended on.
Frequently asked questions
What is data migration in subscription billing? It is the process of moving existing customer, subscription, and payment data from a legacy system into a new platform, mapping and validating each record so accounts keep billing correctly after the switch.
How are stored payment methods migrated without exposing card data? On supported gateways, a merchant can use gateway tokens to keep billing subscribers without moving raw card data at all. Migrating full PCI cardholder data has no self-managed path and is handled by Recurly's Professional Services team, which transfers the credentials securely between providers so customers do not have to re-enter their cards.
What is the difference between self-managed and fully managed migration? Self-managed migration is run by your own team through the platform's API, which is mainly valuable for how quickly a team can move on its own timeline. Fully managed migration is handled by Recurly's Professional Services team, which works closely with the merchant to pull and map the data correctly before running the transfer itself.
How do you avoid billing customers incorrectly after a migration? Run a test migration into a sandbox first, reconcile migrated records against the source by counts and totals rather than spot checks, and watch the first live billing cycles closely for unexpected declines or wrong amounts.
What data usually needs to move in a subscription migration? Customer accounts, active and cancelled subscriptions, coupons, and the stored payment methods, including gateway tokens or NTIDs, that keep recurring charges running. Historical invoices and payment history typically stay behind in the legacy system rather than migrating.
