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.
Contract Data Acquisition & Import/Sync
This section will guide you on how to import or sync contract data from your original platform to the SHOPLINE Subscription App. Depending on your specific situation, you may need to perform API configuration or CSV import.
1. API Import Preparation
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
- In Shopify Admin, go to Settings > Domains to see your store domain (e.g., handle.myshopify.com).
- 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:
-
Create and Develop an App
Go to Settings > Apps > Develop apps in Dev Dashboard.
In the Dev Dashboard, click Create app, enter a name, and click Create.
Click Select Scope, choose permissions (such as App, Order, Customer, Product), then click Release.
-
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.
-
Install the App
Click Install to complete the custom app installation in your Shopify store.
Obtain Shopify API Key (Old Workflow)
- 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.
- Go to Settings > Apps and sales channels > Develop apps.
- Configure Admin API Scopes
- Select all API permissions and click Save.
- Select all API permissions and click Save.
- Install App and Copy API Key
- Go to API credentials, click Install app, and copy the API token from the API credentials section.
- The token is shown only once. Save it securely.
Obtain Recharge API Key
- Create Admin Token
- Go to Tools & App and click Create a token now in the Admin Token card.
- Go to Tools & App and click Create a token now in the Admin Token card.
- 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.
-
Copy API Key
- Go to the API Token section and copy your API key.
- Go to the API Token section and copy your API key.
Obtain Appstle API Key
Go to More > API Access.
Select Create key.
Copy the generated API Key for later use.
| 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
Log in to your SHOPLINE Subscription App admin.
Navigate to Subscription Contracts, click Start Migration, and select your original platform (e.g., Recharge).
Enter your Shopify handle, Client ID, Secret, and Recharge API Key in the pop-up. You can also enable automatic subscription matching.
Click Import Now to validate your API Keys.
After validation, SHOPLINE will import and sync all subscription contract data from Recharge automatically.
2. CSV Import Preparation
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
Log in to your SHOPLINE Subscription App admin.
Go to Subscription Contracts > click Start Migration > choose Batch Import via CSV.
Click Download to get the latest subscription-contracts-template.csv file.
Export Data from Original Platform
Log in to your original subscription platform (e.g., Recharge).
Export all subscription contract data as instructed by the platform.
Format Data and Fill Template
Fill in your exported contract data into the downloaded template, row by row.
Make sure all required fields are filled and data formats (like dates) match the template requirements.
Key Field Descriptions:
| Field Name | Meaning | Required Check | Reference 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 |
| remain_cycles | Remaining Execution Cycles. If no value, defaults to max_cycles. | 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 |
| 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 | 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 argeement 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.
Upload CSV File
Go to your SHOPLINE Subscription App admin.
In the import window, click Next Step.
Upload your completed CSV file by dragging or clicking the upload area.
Select the appropriate payment channel for these contracts.
Click Import and wait for the process to finish.
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 | ||
| 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. |
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:
-
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".
-
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.
| 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.
Customer Steps
To edit or update a contract, customers must first complete the contract upgrade:
Log in: Customer logs in and goes to "My Subscriptions".
Rebinding Prompt: When trying to edit a "Pending Payment Method Update" contract, a pop-up prompts for a payment method update.
-
Contract Upgrade Wizard: Clicking Update Now opens a wizard to review and modify:
Next billing date
Shipping address
Update Payment Method: Customer binds a new payment method.
Confirm: After binding, a message asks if the update is complete.
-
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:
- Export the latest contract data from the original platform.
- Prepare a CSV with only the "Unmanaged" contracts to update. Keep the
external_contract_idunchanged; update other fields as needed. - Re-upload the CSV as described in Chapter 2, Section 2.2. 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".