Subscriptions: Migration Guide

This guide helps you securely migrate your subscription contracts from your current platform (e.g., Recharge or Appstle) to the SHOPLINE Subscriptions app. It will enable you to:

• Minimize Customer Churn: Keep contracts active on your original platform during migration to prevent payment issues and retain customers. 

• Simplify Migration: Use a smooth, reliable process to move your business to SHOPLINE and benefit from enhanced subscription management. 

The guide covers preparation, contract import and sync, results checking, contract management, and customer activation for a smooth start.

Migration Overview

Before You Start Migrating

1. Set Up SHOPLINE Subscriptions

Before migrating, install and set up SHOPLINE Subscriptions.

Make sure you've done the following:

• Installed the SHOPLINE Subscriptions app.
• Created the subscription plans you need. Migrated contracts will link to these plans.
• Set up the contract migration notice under Store Display Settings.
• Turned on the info customers are allowed to update, under Settings, including:
  • Shipping info
  • Subscription frequency
  • Payment method

For details on subscription plans and store display settings, see the article "Subscriptions: Setting Up Recurring Purchases."

2. Migrate Your Basic Store Data First

Before migrating contracts, make sure your basic store data has already been migrated to SHOPLINE. This is required for contract data to map and display correctly. You can use the Multi-platform Store Migration app to help migrate this structured data, including:

• Product data: Make sure all product data has been migrated from your original platform to SHOPLINE.
• Customer data: Make sure all customer data has been migrated from your original platform to SHOPLINE.

Stage 1: Contract Migration

The goal here is to import the subscription contracts themselves into SHOPLINE, including contract status, billing cycle, products, customer, shipping address, and shipping info.

There are two ways to migrate contracts:

• API Sync: For merchants whose original store is on Shopify and whose subscription service is Recharge, Appstle, Loop, or Seal. Note: API sync requires your original store and subscription app to stay active during the migration, which may involve extra costs; please plan accordingly.
• CSV Import: For merchants who don't meet the API sync requirements, or who prefer to prepare a file and import everything in one batch.

Migrating Contracts via API Sync

When this applies:

API sync currently works when:

• Your original store platform is Shopify.
• Your original subscription provider is Recharge, Appstle, Loop, or Seal.
• You can get both your Shopify credentials and the API credentials for your subscription platform.

Step 1: Get Your Shopify Store Credentials

1. In Shopify Admin, go to Settings > Domains to see your store domain (e.g., handle.myshopify.com).
2. Note the "handle" part of your domain.

Obtain Shopify API Key (2026 New Workflow)

From January 2026, some Shopify stores will be managed via the Dev Dashboard. Stores using the Dev Dashboard can no longer get API Keys through Legacy Custom Apps. This update does not affect existing API Keys, which will continue to work as usual in SHOPLINE.

If your store uses the Dev Dashboard, follow these steps to get your Client ID and Secret for dual-system migration:

1. Create and Develop an App

   • Go to Settings > Apps and click Build apps in Dev Dashboard.

     

   • In the Dev Dashboard, click Create app.

     

   • In the Start from Dev Dashboard section, enter a name and click Create.

     

   • Click Select Scope, choose permissions (including App, Order, Customer, Product), then click Release. Please make sure all of the following permissions are checked:

     • read_all_orders

     • read_app_proxy

     • write_app_proxy

     • read_customers

     • read_customer_merge

     • read_orders

     • read_product_feeds

     • read_product_listings

     • read_products

     

   • In the pop-up window, click Release again to confirm.

     

2. Save the Client ID and Secret

   • After creating the app, go to Settings, copy and securely save the Client ID and Secret for SHOPLINE migration.

     

3. Install the App

   • Go to the app Home page and click Install app.

     

   • On the Install app page in your Shopify admin, click Install again to complete the custom app installation in your Shopify store

     

Obtain Shopify API Key (Legacy Workflow Before 2025)

1. Develop and Create an App

   • Go to Settings > Apps and sales channels > Develop apps.

     

   • Click Create a custom app, name your app (e.g., "SHOPLINE Migration App"), and click Create app.

     
     

2. Configure Admin API Scopes

   • Select all API permissions and click Save.

     

3. Install App and Copy API Key

   • Go to API credentials, click Install app, and copy the API token from the API credentials section.

   Important: The token is shown only once. Save it securely.

Step 2: Get API Credentials from Your Current Subscription Platform

You only need to do this for the one platform you're currently using, no need to set up all of them.

Obtain Recharge API Key

1. Create Admin Token

   • Go to Tools & apps > API tokens, then click Create now in the Admin tokens card.

     

2. Configure Admin API Scopes
   • After creating the token, enter the Create an API Token page and name your token.

   • Select all API permissions and click Save.

     

3. Copy API Key

   • Go to the API Token section and copy your API key.

     

Obtain Appstle API Key

1. Go to Appstle Subscription > More > API Access.

   

2. Locate the API Keys section and click Generate key.

   

3. In the pop-up window, enter a name for the API key, select Read & Write — Full access to all API endpoints, then click Create key.

   

4. Copy the generated API Key for later use.

   

Obtain Seal API Key

Obtain Loop API Key

To obtain the Loop Subscriptions API key, please refer to the article Generate Loop API Tokens in the Loop Help Center.

Step 3: Start Syncing Contracts in SHOPLINE

1. Log in to the SHOPLINE Subscriptions app admin.
2. Go to Migration Center and click Start Migration.
3. Choose your original subscription platform.
4. Enter your Shopify handle, Client ID, Secret, and the API credentials for your current subscription platform.
5. If there's an Auto-match subscription plans option, choose it if it fits your needs.
6. Click Import Now.

The system will first check that your credentials are valid. Once verified, it will pull and sync your subscription contract data from the original platform.

Migrating Contracts via CSV File

Step 1: Download the Contract Migration Template

1. Log in to the SHOPLINE Subscriptions app admin.
2. Go to Migration Center and click Start Migration.
3. Choose CSV Import.
4. Download the latest contract import template.

Always use the most recently downloaded template from the admin panel.

Step 2: Export Contract Data from Your Original Platform

Log in to your original subscription platform and export the contract data you want to migrate.

Before organizing your data, make sure:

• The products and variants already exist in SHOPLINE.
• The customers already exist in SHOPLINE.
• Each contract has a unique, stable ID from the original platform.
• Contracts that need to keep billing already include their next billing date.

Step 3: Fill In the Contract Import Template

The contract template is for migrating contract data; you'll need to organize your data into this structure yourself before uploading.

Basic Contract Info

Allowed Status values: ACTIVE, PAUSED, CANCELLED, FAILED, EXPIRED

Billing Cycle Info

Allowed Interval values: DAY, WEEK, MONTH, YEAR

Date and Currency Info

Subscription Plan and Product Info

Allowed Line items adjustment type values: PERCENTAGE, FIXED_AMOUNT

Shipping Address Info

Shipping Info

Step 4: Upload Your Contract CSV File

1. Go back to the CSV Batch Import page.
2. Click Next.
3. Upload your completed contract CSV file.
4. Select the payment channel for each contract, as prompted.
5. Click Import and wait for it to finish.

Stage 2: Payment Migration

Once contracts are migrated, if you want to keep using the original payment method in SHOPLINE, you'll need to upload the payment token separately.

Payment migration doesn't replace contract migration; make sure contracts are successfully imported first, then upload the matching payment tokens.

Before you start, prepare:

• The Original Subscription ID of the successfully imported contract.
• The customer's email.
• The current payment channel and token info actually used by the contract.

Only upload payment tokens for contracts that still need to use the original payment method; you don't need to fill in a token file for contracts that don't need payment migration.

Payment Token File Fields

Each contract row only needs the fields for its actual payment channel; leave the other channels' fields blank.

How to Upload Payment Tokens

1. Confirm the contract has already been migrated.
2. Download and fill in the payment token import template.
3. Double-check the contract ID matches the imported contract exactly.
4. Go to the payment token upload page in SHOPLINE Subscriptions.
5. Upload the file and wait for results.
6. If a results file is provided, download it and fix any failed records.

If a payment token can't be migrated, the contract can stay in "Migrating" status; the customer can still update their payment method later in the Customer Center.

Managing Migrated Contracts

Once migration is complete, you can view and manage all migrated contracts from the Migration Center.

Migrated Contracts List

Go to Migration Center > Migrated Contracts to see all imported or synced contracts. The list usually includes:

Migration Status Meanings

Available Actions

For contracts marked "Awaiting Payment Update" or "No Migration Needed," you can (depending on what your admin supports):

• Add discount codes.
• Filter and export contract and customer lists.
• Send win-back emails to eligible customers.

Getting Customers to Complete the Migration

For contracts that haven't finished payment migration or a payment method update, the customer needs to update their payment method in the Customer Center before the contract becomes "Migration Successful."

Set Up the Contract Migration Notice

In Subscriptions > Migration Center > Contract Migration Notice, turn on the update reminder banner.

Before the customer updates their payment method, it's best not to direct them to edit the contract directly, first explain that they need to update their payment method to avoid confusion during migration.

What the Customer Does

1. Logs in to the store's Customer Center.
2. Goes to My Subscriptions.
3. When they try to edit a contract that's "Awaiting Payment Update" (e.g., changing the billing schedule or shipping address), the system prompts them to update their payment method.
4. They click Update Now to enter the contract update wizard.
5. They confirm or update info like the next billing date and shipping address.
6. They add a new payment method.
7. Once the payment method is updated, SHOPLINE completes the handover, and the contract status changes to "Migration Successful."

Once a customer completes the handover, the merchant gets notified. To avoid double-charging, make sure to promptly handle the matching old contract on the original platform.

Keeping Data Up to Date

Automatic Updates via API

If you've enabled API auto-sync, changes to contract data from Recharge, Appstle, Loop, or Seal (like renewals or status changes) will sync to SHOPLINE's migration contract list in near real-time via webhooks. You don't need to manually update the snapshot info for these "Awaiting Payment Update" contracts.

Manual Updates via CSV

If you used CSV import, and a contract's data changes on the original platform while it's still "Awaiting Payment Update," you can manually update the snapshot info in SHOPLINE.

If you're still running the original contract on the old platform, make sure to sync the update there too.

Frequently Asked Questions (FAQs)

Find answers to common questions about using the dual-system migration solution.

Q1: Why are my imported contracts marked as "Pending Payment Method Update"?

This usually happens when the original payment method (e.g., Shopify Payment) is not supported by SHOPLINE, or payment method migration isn't finished.

Q2: How do I change a contract to "Migration Successful"?

Customers need to update their payment methods in your store for contracts in "Pending Payment Method Update" status.

Q3: Do I need to cancel contracts on the original platform manually?

For CSV imports, once a contract is marked "Migration Successful" in SHOPLINE, you must manually cancel the old contract on your original platform to avoid double-billing. For supported subscription platforms' API imports, SHOPLINE will automatically cancel the old contract via the API.

Q4: Is the Shopify or Legacy E-Commerce Solution order data synced to SHOPLINE after API synchronization?

API sync mainly updates contract data. You must manually sync order data using the Multi-platform Store Migration app.