Take a tour Sandbox Signup
Toggle Mobile Navigation
  • Content

Customer Imports

Migrate Existing Subscribers Into Recurly

You can migrate account and/or subscription data into Recurly without our assistance. However, due to the highly sensitive nature of billing data, we strongly recommend that you leverage our Account & Billing Import service. This is a PCI-compliant process that eliminates risk for you while transferring customer billing data from your legacy provider into Recurly. Our Professional Services organization has dedicated experts available to assist you in subscriber migrations with two services.

Account Information

You can use our create_account API endpoint to recreate your existing customer accounts in Recurly. If you plan to have Recurly manage your credit card or subscription import, do not create accounts beforehand.

Billing Information

We can provide a PCI-compliant transfer of existing subscribers and their billing information from your legacy provider onto the Recurly platform through our account and billing info migration service.

Subscription Information

To migrate the details of your customers’ existing subscriptions into Recurly, you have three options. There are two self-import methods for you to choose from. Alternately, our Professional Services Team can assist you with the entire process: migration of subscriber accounts, their billing information, and their existing subscriptions with our subscription import service.

Customer Subscription Imports

Migrate subscription data for your existing customer base into Recurly with our help, or by using our APIs. Each method allows you to continue delivering a seamless billing experience, making the transition to Recurly transparent to your subscribers.

Import Options

You have three options for managing a migration of your customers’ subscriptions into Recurly:

  • Recurly-managed - We can take you through a formal migration process to bring key customer data into Recurly, addressing questions and concerns along the way. This service includes an import of accounts, billing records, and subscriptions.
  • Self-managed - Manual Invoice Method
  • Self-managed - Free Trial Method

Self-managed Subscription Import Prerequisites

If you choose to import subscriptions yourself, the following tasks must be completed before you can begin your migration of subscriptions into Recurly:

  1. Your Recurly site is in Production mode
  2. All new subscriber sign-ups are being routed to your Recurly site
  3. The account and billing data for your existing subscribers is already migrated into Recurly. We strongly recommended that you leverage our PCI-compliant Account and Billing Import service to migrate this sensitive data. However, if you have access to your customers’ raw billing data, you can follow the steps below.

Self-Managed Imports

Before you can add subscriptions to Recurly, the account and billing info must first be in place.

  1. Account Creation

    Use the Create Account API call. The first step is to create an account inside of Recurly your customer data. At a minimum, you’ll need to define an account_code. The account code will be used as the unique identifier to correlate the accounts with the credit card data, so you’ll want to be consistent in the way you have identified your accounts in the past.

  2. Provide Billing Information

    Use the Billing Info Update API call. For the initial credit card import, the Recurly API does not require the CVV, just the card number and expiration date. The addition of billing information to an account triggers a card authorization to ensure that billing data is valid before saving. Some cards might fail, so you’ll need to reach out to those customers for updated information before proceeding to Step 3.

  3. Create Subscriptions

    • Option 1: Manual Invoice Method

      This step requires you to have subscription plans defined in your Recurly account first. Next, disable the automated communications you want to suppress via your Recurly email template settings. This will prevent your customers from receiving emails when these new subscriptions are created inside of Recurly.

      Use the Create Purchase API to create the subscription with a first renewal date matching the next renewal date, and generate a manual invoice. NOTE: Depending on the Recurly plan that you are subscribed to, you may be liable for manual invoice fees generated using this method.

      Mark the invoice as “paid”, then convert the subscription to automatic collection.

      Importing subscriptions will trigger the charge of a setup fee, if one is configured on the associated plan. To circumvent this, you may consider applying a credit to the account in the amount of the setup fee, before creating the subscription. This will prevent the customer from being charged.

      Considerations

      • Emails would automatically be triggered for new subscriptions, new invoices and paid invoices. We recommend you turn off any customer emails that may be triggered during this process.
      • If you’re using webhooks to trigger any customer communications, we recommend disabling any that would be triggered by a new or paid invoice event in Recurly.

    • Option 2: Free Trial Method

      This step requires you to have subscription plans defined in your Recurly account first. Next, disable the automated communications you want to suppress via your Recurly email template settings. This will prevent your customers from receiving New Subscription Confirmation emails when these new subscriptions are created inside of Recurly, and from receiving Trial Ending emails before the subscription renews for the first time in Recurly.

      Then, use the Create Subscriptions API with a free trial end date specified which corresponds with your next invoice date for each customer. This can accomplished by modifying the trial_ends_at parameter.

      Importing subscriptions in an "in trial" state will trigger the charge of a setup fee, if one is configured on the associated plan. To circumvent this, you may consider applying a credit to the account in the amount of the setup fee, before creating the subscription. This will prevent the customer from being charged.

      Considerations

      • Analytics will not reflect actual results (MRR, Billings, Revenue Recognition, Trial Conversion, Plan Performance)
      • Subscribers can upgrade for free during the trial period due to proration not being calculated. Merchants should block self-subscriber driven changes during trial period
      • Refunds - process credit through previous gateway if possible, or cut a check offline

  4. Disable your Legacy System

    Your customer subscriptions inside your legacy system should be canceled at the end of their current bill cycle, ensuring a seamless transition into Recurly billing at renewal. Once you’ve setup your customer accounts and subscriptions, re-enable Recurly email templates so that your customers are automatically alerted to future invoices or failed payments.