Start Strong
Sell Smart
Manage with Ease
Market to Success

Subscription App: Subscription Contract Migration Guide

This guide helps you securely migrate your subscription contracts from your current platform (e.g., Recharge) to the SHOPLINE Subscription 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.

 

 

Pre-Migration Preparations

Complete Basic Store Data Migration

Before migrating contracts, make sure your SHOPLINE store has finished migrating basic data. This ensures accurate contract mapping and display. Use the Multi-platform Store Migration app to transfer structured store data, including:

  • Product Data: All product data should be migrated from your original platform to SHOPLINE.
  • Customer Data: All customer data should be migrated from your original platform to SHOPLINE.

 

 

Importing Contract Data via API

Currently, API import only supports merchants whose original platform is Shopify and who use Recharge or Appstle as subscription services. Before starting the API import, you need to configure your API Key on the original platform and provide it to the SHOPLINE Subscription App.

Important: Please keep your API keys secure and do not disclose them.

Find Your Shopify Handle

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

Obtain Shopify API Key (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.
      Group 3558256 (1).png

    • In the Dev Dashboard, click Create app.
      Group 3558255 (1).png

    • In the Start from Dev Dashboard section, enter a name and click Create.
      Group 3558257 (1).png

    • Click Select Scope, choose permissions (such as App, Order, Customer, Product), then click Release.
      Group 3558261 (1).png

    • In the pop-up window, click Release again to confirm.
      Group 3558305 (1).png

  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.
      Group 3558264 (1).png

    • On the Install app page in your Shopify admin, click Install again to complete the custom app installation in your Shopify store
      Group 3558265 (1).png

Obtain Shopify API Key (Old Workflow)

  1. Develop and Create an App
    • Go to Settings > Apps and sales channels > Develop apps.
      Group 3558267 (1).png
    • Click Create a custom app, name your app (e.g., "SHOPLINE Migration App"), and click Create app.
      Group 3558306 (1).pngGroup 3558307 (1).pngGroup 3558272 (1).png
      Group 3558326.png
  2. Configure Admin API Scopes
    • Select all API permissions and click Save.
      Group 3558275 (1).pngGroup 3558277 (1).png
  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.

Group 3558279 (1).png
Group 3558329.png

Obtain Recharge API Key

  1. Create Admin Token
    • Go to Tools & apps > API tokens, then click Create now in the Admin tokens card.
      Group 3558285 (1).png
  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.
      Group 3558313.png
  3. Copy API Key
    • Go to the API Token section and copy your API key.
      Group 3558314.png

Obtain Appstle API Key

  1. Go to Appstle Subscription > More > API Access.
    Group 3558293 (1).png

  2. Locate the API Keys section and click Generate key.
    Group 3558315.png

  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.
    Group 3558321.png

  4. Copy the generated API Key for later use.
    Group 3558322.png

Note: API access is a paid add-on. Contact Appstle support to enable it. The cost is $100 per month.

Set Up API Key in SHOPLINE Admin

  1. Log in to your SHOPLINE Subscription App admin.

  2. Navigate to Subscriptions, click Import subscription, and select your original platform (e.g., Recharge).
    Group 3558308 (1).png

  3. Enter your Shopify handle, Client ID, Secret, and Recharge API Key in the pop-up. You can also enable automatic subscription matching. Then, click Import Now to validate your API Keys.
    Group 3558300 (1).png

  4. After validation, SHOPLINE will import and sync all subscription contract data from Recharge automatically.

Importing Contract Data via CSV

If API import is not possible, or you want to import contracts with payment methods, you can manually import contract data using a CSV file.

Download Official Template

  1. Log in to your SHOPLINE Subscription App admin.

  2. Go to Subscription Contracts, click Start Migration, then choose Batch Import via CSV.

  3. Click Download to get the latest subscription-contracts-template.csv file.
    Group 3558301 (1).png

Export Data from Original Platform

  1. Log in to your original subscription platform (e.g., Recharge).

  2. Export all subscription contract data as instructed by the platform.

Format Data and Fill Template

  1. Fill in your exported contract data into the downloaded template, row by row.

  2. Make sure all required fields are filled and data formats (like dates) match the template requirements. Refer to the key field descriptions below:

Field Name Description Required Example
storeHandle SHOPLINE Store Handle Required stgyangcheng2
id_processed Third-party Contract Number Required 1111111
status Contract Status: ACTIVE, CANCELLED, FAILED, EXPIRED (Paused is missing) Required ACTIVE
interval Subscription Time Interval Period (DAY, MONTH, WEEK, YEAR) Required DAY
interval_count Interval Quantity. E.g., for "buy every 3 weeks", the value here is 3. Required 2
max_cycles Maximum Execution Cycles. If no value, defaults to an indefinite contract.   12
min_cycles Minimum Execution Cycles Required 2
periods Number of fulfilled orders. If there is no value, it defaults to 0.   4
processed_at Third-party Contract Creation Time   2024-12-02T12:00:00
next_billing_date Next Contract Execution Time [First execution time after migration] Required 2025-01-28T12:00:00
currency_code Currency Information Required MYR
line_items_amount Selling Price of Product, before product discounts Required 100
line_items_variant_id SHOPLINE Product Unique SKU ID Required 18066984575317893633362795
line_items_product_source Product SKU Source    
line_items_quantity Product Quantity, must be greater than 0, maximum limit 99999 Required 2
line_items_adjustment_type Discount Type, e.g., PERCENTAGE, FIXED_AMOUNT   FIXED_AMOUNT
line_items_adjustment_value Discount Value   20
customer_id Subscription Customer SHOPLINE Customer ID Required 4603168091
email Subscription Customer Email   xuweihang@shopline.com
delivery_first_name First Name   bing
delivery_last_name Last Name   tang
delivery_name Nickname    
delivery_phone Contact Phone   13123334444
delivery_country Country or Region Name   United States
delivery_country_code Country or Region Code, two-digit abbreviation (ISO-3166-1), converted by SL Required US
delivery_province State or Province Name   Ohio
delivery_province_code State or Province Code, input standard code (ISO-3166-2), converted by SL Required WA
delivery_city City Name   Cleveland
delivery_city_code City Code    
delivery_company Company Name   FireXuan-USD
delivery_district Administrative District Name    
delivery_district_code Administrative District Code   94101
delivery_address1 Detailed Address Info 1, for supplementary info   University Hospital Drive
delivery_address2 Detailed Address Info 2, for supplementary info   RR 2 Box 260
delivery_zip Shipping Address Postal Code   44106
delivery_id SHOPLINE Shipping Plan Name   Multi Delivery Test Plan
delivery_amount Shipping Price   50
selling_plan_id Subscription Plan ID, from SHOPLINE Subscription App Required 14066622198340539053032795
channel_customer_id Customer ID from payment channel. *Required if the contract’s payment channel is Stripe or SLP    
payment_method_id Payment Method ID from payment channel. *Required if the contract’s payment channel is Stripe or SLP    
account_name Customer account name from Paypal. *Required if the contract’s payment channel is Paypal    
billing_agreement_id Customer billing agreement id from Paypal. *Required if the contract’s payment channel is Paypal    

Splitting Contracts by Payment Channel

SHOPLINE supports subscription payments via three channels:

  • SHOPLINE Payment

  • Stripe

  • PayPal

If your contracts are linked to any of these channels, split them into separate CSV files. When importing, choosing the correct payment channel will bind the contracts and complete the migration instantly.
Group 3558309 (1).png

Upload CSV File

  1. Go to your SHOPLINE Subscription App admin.

  2. In the import window, click Next Step.

  3. Upload your completed CSV file by dragging or clicking the upload area.

  4. Select the appropriate payment channel for these contracts.

  5. Click Import now and wait for the process to finish.
    Group 3558323.png

 


Import Task Status & Result Inquiry

Regardless of whether you use CSV import or API sync, you need to know how to view and manage import/sync results.

Task Progress and Status Display

When you click Import Now, the system backend will start an import process.

  • Closing the import pop-up will not stop the import task; it will continue in the background.

  • Please note: Only one import task can run in the background at a time. You cannot start a new import task before the current one is completed.

After the import task is completed, there will be three possible statuses:

  • Import Successful: All contracts obtained via Recharge API or uploaded by you via CSV have been imported successfully.

  • Import Partially Successful: Some contracts failed to import successfully, possibly due to data mismatch, format non-compliance, etc. You can download the result file to find the reasons for import failures.

  • Import Failed: No contracts were imported successfully. You can download the result file to find the reasons for import failures.

Download Result File

  • After the import task is completed, if the task result is Import Partially Successful or Import Failed, you can click the Download button to download the import result file.

  • The result file (CSV format) will include the contract ID and "Failure Reason", clearly indicating the detailed reason for import failure for each contract data row.

  • You can correct the data in the original CSV file based on the failure reasons and re-upload it to complete the import of remaining contracts.

 

 

Migration Contract Management

This section explains how migration contracts appear and are managed in the SHOPLINE admin, and clarifies the different migration stages.

Migration Contract List and Stages

Log in to your SHOPLINE Subscription App admin, go to the Subscription Contracts page, and click View Migration Contracts to access the Migration Contracts page.

Migration Contract Data Report

The Migration Contracts page shows three main metrics:

  • Total Migration Contracts: Number of contracts in the migration list.

  • Successful Migration Contracts: Contracts with a "Migration Status" of "Migration Successful".

  • Pending Payment Method Update Contracts: Contracts that are "Active" or "Paused" with a "Migration Status" of "Pending Payment Method Update".

Migration Contract List

This list displays all imported or synced migration contracts. Key fields related to contract migration are included.

Field Name Field Definition Field Value Enum Field Value Definition
Migration Method Current contract import method CSV Import Contract was imported via CSV
Recharge API Contract was automatically synced via Recharge API
Loop API Contract was automatically synced via Loop API
Seal API Contract was automatically synced via Seal API
Migration Completion Time The time when the contract status was updated to "Migration Successful" Specific Time Point The time when the contract status was updated to "Migration Successful"
Migration Status Whether the current contract has been taken over by SHOPLINE and completed payment method update Pending Payment Method Update Customer has not yet completed the update operation for the current contract; the contract is still running on the original platform.
Migration Successful Customer has updated the current contract; the contract has been taken over by SHOPLINE and needs to be cancelled on the original platform.
No migration needed If the contract status on the original platform is “Cancelled,” “Failed,” or “Completed,” it is considered that the contract does not need to be migrated.

Filter Function

Use the filters at the top of the page to quickly find contracts. Filter options include:

  • Migration Status: Pending Payment Method Update, Migration Successful.

  • Original Platform Contract Status: Active, Paused, Cancelled, Expired.

  • Migration Method: Recharge API, CSV.

  • Migration Completion Time: Select a date range.

Customer Recall Operation

To encourage customers to update their payment methods as soon as possible, thereby converting "Pending Payment Method Update" contracts to "Migration Successful", you can utilize the automatic email function:

  1. Filter Contract List: Use the filter function on the contract list to filter contracts where:

    • Migration Status is "Pending Payment Method Update".

    • Platform Contract Status is "Active" or "Paused".
      Group 3558310 (1).png

  2. Recall Method Selection: A pop-up will offer two recall methods:

    • Automatically Send Recall Emails: The system will send pre-set recall emails to customers corresponding to the filtered contracts. You can edit the template content. The recall CTA will link directly to the customer's contract management admin (not directly to the payment method update link).

    • Export Contracts and User List to Email: You can choose to export the currently selected contract list to your designated email, allowing you to conduct custom marketing campaigns or manual follow-ups.
      Group 3558324.png

Note: Set up contract migration notifications before contacting customers to ensure they receive clear information. See Contract Migration Notification Settings for configuration details.

 

 

Customer Activation Process Overview

This section explains how customers can update their payment methods to change contracts from "Pending Payment Method Update" to "Migration Successful".

Contract Migration Notification Settings

During migration, customers can't edit subscription contracts. Enable the "Prompt Update Notification Banner" to remind customers to update payment methods. After migration, editing is restored.

Configure this in Subscription App > Storefront display > Migration Notification.
image 43 (1).png

Customer Steps

To edit or update a contract, customers must first complete the contract upgrade:

  1. Log in: Customer logs in and goes to My Subscriptions.
    Group 3558302 (1).png
    Group 3558303 (1).png

  2. Rebinding Prompt: When trying to edit a "Pending Payment Method Update" contract, a pop-up prompts for a payment method update.

  3. Contract Upgrade Wizard: Clicking Update Now opens a wizard to review and modify:

    • Next billing date

    • Shipping address

  4. Update Payment Method: Customer binds a new payment method and clicks Update payment.
    Group 3558304 (1).png

  5. Confirm: After binding, a message asks if the update is complete.

  6. Customer clicks Confirm. The system checks for the update.

    • If successful, the contract status updates to "Migration Successful" and normal management is enabled.

    • If failed, a prompt appears to retry.

Merchant Notification

When a customer successfully updates their payment method, you'll receive an email notification.

 

 

Data Maintenance and Updates

Learn how our system updates contract data to maintain accuracy.

API Automatic Updates

If API synchronization is enabled, contract changes from Recharge (like renewals or status updates) are automatically synced in near real-time to the SHOPLINE migration contract list via Webhook. No manual action is needed to update "Pending Payment Method Update" contracts.

CSV Manual Updates

If using CSV import, and a "Pending Payment Method Update" contract changes on the original platform, you can manually update the snapshot in SHOPLINE.

Steps:

  1. Export the latest contract data from the original platform.
  2. Prepare a CSV with only the "Unmanaged" contracts to update. Keep the external_contract_id unchanged; update other fields as needed.
  3. Re-upload the CSV as described in CSV Import Preparation. The system will update contract snapshots based on external_contract_id.

 

 

Frequently Asked Questions (FAQ)

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 Recharge API imports, SHOPLINE will automatically cancel the old contract via the API.

Q4: Is the Recharge order data synced to SHOPLINE after API synchronization?

API sync mainly updates contract data. You must manually sync order data using the "Migration App".