This article is written specifically to cater to migration from subscription solutions that are outside of the Shopify ecosystem (or) are partially managed within Shopify

Types of custom platforms

Custom platforms / implementations vary greatly from one case to another and would fall under two basic categories.

1. Subscription Management through Payment Provider

   1. Stripe → https://stripe.com/docs/billing/subscriptions/overview

   2. Braintree → https://developer.paypal.com/braintree/docs/guides/recurring-billing/overview

   3. Authorize → https://developer.authorize.net/api/reference/features/recurring-billing.html

2. Subscription Management using vaulted payments
   In this method the subscription management is separated from the PSP and the implementation would be designed to place a charge on the vaulted token stored in the PSP.

Migration steps and Phases

When shifting from a custom platform there are usually three distinct phases, and a brief overview is provided for each stage before delving into the detailed specifics of each stage

Migrating Customers (and/or) Order information

Here is a quick visualisation of the most important objects / elements that are usually present for each customer object, In this first phase the aim is to import the Personally Identifiable info into the platform

graph TD     
Customer  --> Address     
Customer  --> Orders     
Customer  --> PaymentInformation     
Customer  --> SubscriptionContracts 

This phase will cover these two sections and important guides / links are provided below for reference

1. Customer Import

   1. Address

   2. Email

   3. Contact details

   4. Other information

2. Order Import

   1. Order value

   2. Line items

   3. Address used for order

   4. Discount information

Migrating Payments

Migrating Payment from your old platform consists of the following steps and the flowchart would be able to give the merchant a good understanding of the entire process of importing payments into Shopify.

graph TD
    A[Check for supported payment provider]
    A -- Not supported --> B[Migrate from current PSP to supported provider]
    B -- After migration --> C[Connect PSP as secondary/primary provider]
    A -- Supported --> C
    C -- Import tokens --> D[Shopify's vault]
    D -- Store and sync --> E[Shopify tokens in Loop's DB]

Important note and warning →

Check if your Payment Provider is Supported by Shopify for Subscriptions

To be able to import payments into Shopify - you would need to use one of the supported payment providers that are mentioned in this document detailed by Shopify. Exhaustive documentation is provided in Shopify’s developer documentation.

1. Braintree (can only be used as secondary)

2. Stripe (can also be used as sole primary gateway)

3. Authorize (can also be used as sole primary gateway)

4. PayPal Express (can be used separately without any interferance from the primary and secondary gateways)

 graph TD
    subgraph SecondaryProviders
        Braintree
        Stripe
        Authorize
        PayPal_Express
    end

    subgraph PrimaryProviders
        ShopifyPayments
    end

    Shopify --> SecondaryProviders
    Shopify --> PrimaryProviders

How does an ideal payment setup look like in Shopify when migrating into the ecosystem.

An ideal setup would be to use Shopify Payments as your main PSP with either Braintree / Stripe as your secondary for processing your subscription renewals. As this way you can leverage the cheaper txn charges offered by Shopify Payments while being able to import and charge your old subscriptions in Shopify

Shopify Payments + Braintree (or) Shopify Payments + Stripe (or) Shopify Payments + Authorize

How to connect a secondary payment provider in Shopify ?

To connect Stripe / Braintree as a secondary provider in your Shopify account, simply follow the below steps.

1. Head over to Loop > Settings > Migrate customers and payment methods
   

   

2. Choose the Payment provider that you want to connect as secondary and click on the green Connect button
   

   

3. This will take you to an Oauth Page like shown below, enter your credentials to login
   

   

4. If you have more than one account - choose the same account that is connected to your old platform / store
   

   

How do i import the tokens into Shopify?

Prerequisite →

If all the prerequisites are met - then the merchant can share the export and API token from the PSP that loop team can use to import these PSP tokens into Shopify to create something called RemoteCreditCard

What needs to be shared with Loop team →

1. Customer Export from Payment Provider

   1. Stripe

   2. Authorize

   3. Braintree

2. API token from Payment Provider

   1. Stripe

   2. Authorize → to get name and txn key [guide]

      1. name → Merchant’s unique API Login ID.

      2. transactionKey → Merchant’s unique Transaction Key.

   3. Braintree

      1. merchant_id

      2. public_key

      3. private_key

How the process looks like on Loop’s side →

1. Loop team will convert the customer data export from the PSP to standard format supported by Loop

2. We will then hit the following endpoint POST /admin/api/2023-07/graphql.json with the CustomerPaymentMethodRemoteCreate mutation

3. The response is then stored and reverse mapped with the input data to provide a 1:1 mapping between the source tokens and the shopify unique gid’s

Standard Payment Import format on Loop →

Verification of Payment Method Import

Once the payment tokens have been successfully imported by the team you should be able to see it in shopify under the customer object as shown in the below screenshot for every card that was imported as part of this process.

Migrate Subscriptions

The flowchart below details how the overall subscription migration process would look like and gives an end to end perspective on the stages in this process.

graph TD
    A[Step 1: Check conditions]
    A -- Subscription Management through Payment Provider --> B[Fetch subscription data from PSP or custom solution]
    B --> C[Convert data to Loop migration template]
    C --> D[Share data with Loop team]
    D --> E[Loop migration team recreates subscriptions]
    E --> F[Loop migration team shares detailed report with merchant]
    A -- Subscription Management using vaulted payments --> G[Fetch subscription data from custom platform / solution]
    G --> C

Check for type of custom platform

Since there is a vast difference in how the data is handled between the types of platforms explained here, merchant can decide their source of truth to fetch subscription information from.

1. Usually when Subscription Management through Payment Provider - the information related to cadence, address and line item information are present directly on the PSP itself. But this depends on how your solution has implemented / made use of the PSP APIs.

2. When the custom platform uses vaulted payments - only the payment related information resides in the PSP and not much more. The platform leverages the PSP only for charges and the source of data would be the custom platform itself.

Convert data to Loop migration template and share with Loop team

We provide a standard subscription migration template which would need to be filled in by the merchant’s team with the data that we can use to import the contracts to Loop.

This sheet provides a good understanding of all the fields and the formats that we would need for the migration →

Internal migration process and Report

We have developed internal systems that make use of Shopify GraphQL APIs to create subscriptions in Loop with the data from the standard template. These endpoints are not exposed to the public and is only available for internal use as of now.

The core implementation that we have used is documented by Shopify themselves in this article and these are the same mutations and steps that we use for the migration internally as well.

Here is the detailed report format that we share to our merchants →

The statistics is grouped first on the MIGRATION STATUS and then grouped by status and the numbers are on the third column

1. MIG STATUS → can be two states COMPLETE / FAILED

2. status → can be one of four states ACTIVE / CANCELLED / PAUSED / EXPIRED

3. COUNTA of platform_subscription_id → is a countunique(platform_subscription_id)

The detailed export contains the following fields →

1. All the fields that are present in the Subscription Migration Format

2. ERR → field shows the error that was encountered while importing sub to Loop

3. MIG STATUS → Subscription level migration status

4. LOOP SUB ID → Subscription contract ID in Loop for the migrated subscription