Migrating from FreshBooks to Stripe for invoicing

For years, the Jefferson County PVA website has used FreshBooks for invoicing subscriptions to users. While FreshBooks previously met PVA needs, in the last year or two there have been numerous bouts of API downtime and a confusing API migration that led the VIA team to explore other solutions.

Knowing FreshBooks was already using Stripe for the actual payments, our development team began looking into the Stripe Invoice product as a replacement service, to fully integrate into Stripe. As part of this process, we had to consider how all of the data would migrate, how we would need to implement this on the website, how we would handle prorations, and the actual rollout of all this to an active subscriber base.

Migration

As noted earlier, FreshBooks already uses Stripe to handle the payments in the backend while FreshBooks sits on top and provides the invoicing layer. Migrating to Stripe cuts out the middleman, but also involves migrating all the user subscriptions from Stripe to Stripe — sounds strange but FreshBooks organized the subscriptions in a manner that our team needed to assess and change.

High level, the first step was to create new subscription products in Stripe. Once that was completed and documented, we imported the existing customer base into Stripe so every user was at least accounted for as a customer. At this point, Stripe was populated with usable data and products.

While not necessarily falling under the migration portion, the next step required adding new Stripe-related fields to our local subscriber database and adjusting the registration process to use Stripe to process payments and invoicing.

This total process was QA'd heavily, with pages of scenarios created to address all the known possible outcomes and multiple people testing each scenario out, to account for variability.

Proration

The biggest challenge in migrating existing subscriptions into our new subscription system was doing it in a timely manner while not creating too many artifacts.

The migration can be done when a user's subscription expires, but the PVA offers yearly subscriptions in addition to monthly and day passes, so in this case the migration couldn't be completed for at least a year as waiting for subscriptions to end wasn’t possible.

In the case of yearly subscriptions, the subscription would essentially start on the day of migration and a user would receive a proration of what they paid minus what time they have already used.

For example, if a PVA customer paid $400 for a yearly subscription 3 months ago, then they’ve used 25% of it (or $100). They would be prorated $300 and then invoiced $100 for the new subscription. Again, that subscription would basically restart on the day of migration.

Batching Rollout

To prevent any sort of bug from affecting the entire user base, the rollout of the Stripe invoicing system was limited to batches of users, starting with a select ten and increasing every week by a few hundred. This process was completely automated, sending a notification a week before and migrating the subscriber to Stripe the following week, issuing the proration, and informing the user.

During the rollout, the FreshBooks invoicing system was still live, with both systems being side by side. New subscribers would be funneled through Stripe while users not in that week's batch would see no difference.

As part of any new large feature, we prioritized QA, while also knowing that it wouldn’t be possible to detect all bugs. We were prepared for this and did in fact encounter some during the rollout. However, with this batched rollout, any bug didn't affect the entire user base and we were able to fix it without major disruption.

Notifications

As mentioned above, users that were to be migrated were notified a week earlier and again on migration, with a link to pay their new Stripe invoice.

We were strategic in our approach of batching the rollout, so that our support team wasn’t flooded with questions at once, but rather in timely groups. This allowed us to assist PVA customers in the most efficient way possible.

In addition to email notices, banners were placed on the website notifying users of the move from FreshBooks to Stripe, and supporting copy and documentation were written beforehand to ensure ease and organization for our support team.

Retrospect

Going into this migration, our team knew we were in for a challenge as the site was live and active with thousands of subscribers. All of our planning and QA'ing paid off, as we only encountered the expected minor bugs coming out of the batched release.

While the batching is still active, the project has been a success overall, as users had/are having a relatively seamless process moving invoicing systems and now the PVA has a more steady and robust invoicing system powered by Stripe.

VIA has the ability to create custom eCommerce experiences and integrate existing platforms and solutions such as Stripe, PayPal, WooCommerce, and Shopify to provide a tailored experience. Contact us today for all of your development needs.