How to Plan a WooCommerce Subscription Migration

WooCommerce, one of the most successful e-commerce platforms for WordPress, offers a popular Woocommerce Subscriptions plugin that allows developers to integrate payment processing tools like Stripe. Despite high-quality documentation from WooCommerce, my team and I discovered firsthand that the process of migrating subscriptions to WooCommerce can prove to be tricky. Successful subscription migration to WooCommerce requires careful planning, timing optimization, and consideration of possible outcomes.

We successfully migrated subscriptions from a custom Laravel based system into WordPress using the WooCommerce Subscriptions plugin without any glitches. Since our successful migration, other developers have reached out and asked me to share my experience. You can find one such reply to an email on my personal blog. In my reply, I do my best to describe the requirements of the process, however, as you can imagine, the rabbit hole runs deeper than can be explored in one email. 

This article provides an overview of the planning process involved in migrating subscriptions to WooCommerce and reviews some of the considerations I made in my own process.

How to plan WooCommerce subscription migration

Every migration is a bit different. While I can't provide a formula that would work ubiquitously in any given situation, I can share the questions you need to ask to accurately diagnose your own migration scenario and come up with a subscription migration master plan. 

Here are 9 questions you should ask before devising a plan to migrate subscriptions to WooCommerce:

1. Who is your current payment processor and what does it do?

In our case, the payment processor was Stripe. Stripe can register subscriptions or your website may send orders to create new subscriptions, cancel existing subscriptions, query users, and determine payment status, among other operations. Because all recurring payments may be registered in Stripe, you will need to plan how to avoid continued Stripe charges even after you disconnect your old website.

2. What are your current membership and subscription plans?

We worked with three membership plans: Trial, Regular and Elite. Each plan had different access levels and rights. In this post, I use the term 'membership' to discuss access levels and rights. I use the term 'subscription' to refer to the payment amount, payment schedule, and recurring dates for charges.

Perform an audit of the current users and their payment plans to assess all potential scenarios and decide how to deal with each type of subscription plan. We followed these steps to audit subscription plans:

• Create CSV files from the subscriptions present in the old Laravel website and cross-check subscriptions with the CSV exports made from Stripe.
• Decide how to deal with each group in order for subscriptions to continue seamlessly as if they were never migrated.
• Check if customers have any credit card information stored in Stripe or determine if customers are using other forms of payment.
• For the users that were in Stripe, check that their bank has authorized Stripe for recurring charges.
• Compile a master table to be audited by the client against their own records and other systems.

We developed scripts based on this master table. Still, new users were subscribing in the old system. We kept a log on any new subscribers coming whose subscription would expire before the migration date (unless they would renew).

3. What are your new membership plans?

We kept the membership plans as they were using the WooCommerce Memberships add-on plugin. There were some minor changes in how we handle new Trial memberships but we were able to configure the plugin to resolve any potential issues.

4. What are your new subscription plans?

We implemented standardizations on how future payments would be received and in how access rights would be granted. We used a custom plugin written on top of WooCommerce Memberships to handle discrepancies in how Laravel and Woocommerce deal with access rights.

5. How will you deal with special cases?

Difficulty arises in situations where users pay by check have or have existing memberships and subscriptions with special installments or prorated amounts. We found that generating and applying special coupons to these subscriptions was the best solution. Thanks to our work in auditing memberships and subscriptions, we were able to quickly identify and remedy the special cases. 

6. What is your new payment processor and what can it do?

Keeping Stripe as our payment processor alleviated some work as we only needed to migrate users and subscriptions on the website side (from Laravel to WordPress). On the other hand, because there was no old credit card processor to turn off, we had to ensure that Stripe didn't double-charge customers. Disconnecting the old system from Stripe doesn't ensure that Stripe will discontinue processing subscription charges made with credit cards.

One potential solution (do not do this!) would be to disconnect the old site, delete all Stripe subscribers, migrate subscribers from the old website to the new website, and let the new website register the subscribers in Stripe. But why delete subscribers from an already working credit card processor when they are being charged correctly?

Remember that a user needs to give consent for recurring credit card charges. If the credit card processor is working fine and you don't intend to ditch it, let it do its job and work your websites around the core charging mechanism.

7. What are the requirements for the continuation of subscriptions?

If you are migrating to a new credit card processor and website, the processors you are using should do the following: 

• Migrate from the old credit card processor to the new credit card processor 
• Match the subscriptions in the new website
• Disconnect the old website and turn off the old credit card processor

We only migrated users and subscription information from the old website to the new website, retaining the credit card processor. We needed to ensure that when we registered the subscriptions in WooSubscriptions that they were matched with the same subscriptions in Stripe with the correct future charge dates to avoid continuous double charges.

WooCommerce Subscriptions and the Stripe WooCommerce plugin allow for two fields to be populated: "Stripe Customer ID"  and "Stripe Source ID." Make sure that these fields are accessible from the Stripe export CSV.

Make sure that the registered charge from the new system is exactly one "billing period" from the last registered and scheduled charge made from the old system. To achieve this, WooCommerce Subscriptions allows a few fields: 

• Payment Schedule (every) x (days, months, years, etc.) 
• Start Date 
• Trial End
• Next Payment
• End Date

To match the subscription with the correct access right, add the matching membership to the new subscription in the "Add item (product)" field. To better understand how these fields work, take a look at a video demonstration on manual subscription creation on the WooCommerce docs site.

These fields are golden. With the right plan, you can achieve a lot, especially if you couple them with other plugins (more on that later):

• Payment Schedule - Match the payment schedule for which the user subscribed
• Start date - Use this field if users should be able to access the subscription prior to the migration date
• Trial - Should not affect existing subscriptions
• Next payment date - WooCommerce Subscriptions tells Stripe when to make the next charge. This will ensure that subscribers are not double charged so long as the old system was disconnected from Stripe before the next billing cycle.
• End Date - Depending on the subscription type, the subscription may continue indefinitely or expire. For users with regular payments, all the above fields need to be populated.

To automate subscription reminders, WooCommerce has a basic email scheduling system that works in most cases. We needed for a more dynamic email reminder system, so we coupled the WooCommerce Subscriptions plugin with the WooCommerce Follow Ups add-on. We were able to segment users that prepaid for the full year and reminded them to come back and subscribe for a continuous subscription. Similarly, reminders and PDF invoices were sent (using the WooCommerce PDF Invoices & Packing Slips plugin) to older subscribers as well as those who pay by check. Subscribers who did not have a Stripe Customer ID or Stripe Source ID the system received payment failure emails to prompt them to register a credit card in Stripe. 

8. When is the best time to perform the migration?

If recurring charges are made on a monthly or quarterly basis, plan your migration for a week that has the fewest scheduled charges. Here are a few tips to optimize migration timing:

• Set aside a whole week to make timely backups, test scripts to run, run migration scripts, and anticipate any unforeseen issues.
• Perform a mock migration to a staging or sandbox site running your scripts in order to estimate the time required. 
• Perform a double migration, initial migration, and then a second migration for new subscribers who signed up on the old site while you were performing the migration.
• Plan to have the old site up during and after migration until you run the test and perform quality assurance. 
• Keep the old site in a sandbox environment, disconnected from the payment processor for a while even after the new site has been launched to keep as a reference.

9. What is required for a successful migration?

Make sure you have the following before you run any migration scripts or do any manual migration:

• New meta fields for users to store legacy data, not just the ones WordPress supports by default
• A unified subscription table from the old system and old payment processor export (audited and revised)
• A plan on how to migrate each group of users
• Separate scripts for each user type (if using scripts for migration)
• A plan on how to manually migrate these users if choosing manual migration process

Before you decide on how you will perform the migration, review your options for migrating subscriptions on the WooCommerce docs page (import manually, use a bulk subscription CSV editor, or create custom import scripts). The most effective method will depend on the complexity of your system, allocated time and budget, long term plan, and your team's WooCommerce experience.

WooCommerce Subscription Migration Planning Takeaways

WooCommerce and its subscription addon is a well-rounded platform with effective documentation, but you have to know exactly what you want to achieve before you make the jump. You have two options: 1) extend Woocommerce and WooCommerce Subscriptions with custom plugins to fit your needs or; 2) make your needs conform to solutions provided by the many extensions and addon plugins on the Woocommerce marketplace.

Doing the research, asking the right questions, devising a plan, and making the right decisions on which tools to use is the key to success. With these considerations, you can assemble an orchestra of plugins, each attuned to the needs of subscribers, website administrators, and credit card processors alike.