Start Strong
Sell Smart
Manage with Ease
Market to Success

订阅式电商：订阅合同搬迁指南

本文旨在帮助您将原订阅平台（如 Recharge）的订阅合同，平滑、安全地迁移至 SHOPLINE 订阅电商 插件。此方案致力于：

  • 降低客户流失：在合同迁移过程中，确保原有平台管理的合同能继续运行，避免支付中断导致客户流失。

  • 降低搬迁难度：提供灵活、可靠的迁移路径，让您无忧地将业务转移到 SHOPLINE，享受更强大的订阅管理能力。

本指南将详细介绍搬迁前的各项准备工作、合同导入/同步的步骤、结果查询、合同管理以及客户端激活流程，助您轻松上手。

 

 

搬迁前置准备

完成店铺基础数据搬迁

在开始合同迁移之前，请务必确保您的 SHOPLINE 店铺已完成基础数据的搬迁工作，这是合同数据能够正确映射和展示的前提。您可以使用 多平台店铺一键搬迁 插件帮助完成店铺结构化数据搬迁，包括如下数据：

  • 商品数据：请确保所有的商品结构化数据都已从原平台搬迁至 SHOPLINE

  • 客户数据：请确保所有的客户结构化数据都已从原平台搬迁至 SHOPLINE
     

 

合同数据获取与导入/同步

在此将指导您如何将原平台的合同数据导入或同步至 SHOPLINE 订阅电商插件 。根据您的具体情况，可能需要进行 API 配置 或 CSV 导入。

 

API 导入准备

目前 API 导入仅支持原平台为 Shopify，且使用 Recharge 或 Appstle 进行订阅服务的商家。在开始 API 导入之前，您需要在原平台配置好 API Key，并提供给 SHOPLINE 订阅电商插件。

重要：请妥善保管您的 API 密钥，切勿泄露。

获取 Shopify Handle

  1. 请前往 Shopify 后台，【设置】 > 【域名】，查看你的店铺域名（如 handle.myshopify.com）

  2. 记录 handle.myshopify.com 中的 handle

获取 Shopify Client ID 和 Secret 流程（新版流程）

自 2026 年 1 月起，Shopify 按照灰度方式，将部分店铺切换至 Dev Dashboard 进行管理。切换至 Dev Dashboard 的店铺不再支持通过 Legacy custom apps 获取 API Key。Shopify 更新不会影响到旧版流程中已经应用的 API Key，若您之前在 SHOPLINE 已经添加过 API Key，之后仍可以继续使用。

若您被切换至 Dev Dashboard，请按照下列新版流程获取 Client ID 和 Secret，以用于双系统搬迁流程。

新版流程如下：

  1. 开发并创建应用

    • 进入设置，点击【应用】>【在 Dev Dashboard 开发应用】
      Group 3558256.png

    • 进入 Dev Dashboard 后台，点击【Create app】，输入自定义的应用名称，并点击【Create】
      Group 3558255.pngGroup 3558257.png

    • 点击【Select Scope】，下拉选择包含 App、Order、Customer、Product 在内的权限后，点击【Release】
      Group 3558261.pngGroup 3558305.png

  2. 保存 Client ID 和 Secret

    • 创建成功后，点击【Setting】，复制并保存  Client ID 和 Secret，后续将用于 SHOPLINE 双系统搬迁。

  3. 安装应用到 Shopify 店铺

    • 点击【Install】，完成 Shopify 自定义应用的安装流程。
      Group 3558264.png
      Group 3558265.png

获取 Shopify API Key 流程（旧版流程）

  1. 开发并创建应用

    • 进入设置，点击【应用和销售渠道】>【开发应用】
      Group 3558267.png

    • 进入创建自定义应用界面，命名【应用名称】自用即可，并点击【创建应用】
      Group 3558306.png
      Group 3558307.pngGroup 3558272.pngGroup 3558274.png

  2. 配置后台 API 范围

    • 创建成功后，下滑页面全选所有 API 权限，点击【保存】
      Group 3558275.pngGroup 3558277.png

  3. 安装应用，并复制 API key

    • 前往 API 凭证界面，点击【安装应用】后，在【API 凭据】栏位即可获得 API token。
      注意：token 仅展示一次，可单独保存。
      Group 3558279.png
      Group 3558329.png

获取 Recharge API Key 获取流程

  1. 创建 Admin Token

    • 进入 Tool & App，在 Admin Token 卡片内点击【现在创建】
      Group 3558285.png

  2. 配置后台 API 范围

    • 创建成功后，进入创建 API Token 界面，按需填写 Token 名称

    • 下滑页面全选所有 API 权限，点击【保存】
      Group 3558288.png

  3. 回到后台，并复制 API key

    • 前往 API Token 界面，在【API key】栏位即可获得 API token
      Group 3558290.png

获取 Appstle API Key 流程

  1. 创建 API Key，进入【More】> 【API Access】
    Group 3558293.png

  2. 点击【Create key】
    Group 3558295.png
    Group 3558297.png

  3. 创建成功后，点击复制 API Key 用于后续搬迁流程
    Group 3558299.png

注意：Appstle 的API功能为附加功能，需要联系 Appstle 客服开通。附加费用为 $100/月

在 SHOPLINE 后台配置 API

  1. 登录 SHOPLINE 订阅电商插件后台

  2. 进入订阅合同页面 > 点击【开始迁移】> 选择搬迁的原平台。（以 Recharge 为例）
    Group 3558308.pngimage 35.png

  3. 在弹窗中填入您从 Shopify 获取的 handle、Client ID、Secret，以及从 Recharge 获取的 API Key，按需选择是否自动匹配订阅计划。
    Group 3558300.png

  4. 点击【立即导入】按钮，系统将验证您的 API Key 是否有效。

  5. 若验证有效，系统后台将自动开始从 Recharge 平台拉取所有订阅合同数据，并同步至 SHOPLINE。

CSV 导入准备

若您不满足 API 导入的使用条件，或您希望导入「带有支付方式的合同」，则可以通过 CSV 文件手动导入合同数据：

下载官方模板

  1. 登录 SHOPLINE 订阅电商插件后台

  2. 进入订阅合同页面 > 点击【开始迁移】> 选择【通过 CSV 批量导入】

  3. 点击【下载】按钮，获取最新的 subscription-contracts-template.csv 文件
    Group 3558301.png

从原平台导出数据

  1. 登录您的原订阅平台（如Recharge）

  2. 导出您的所有订阅合同数据

格式化数据并填写模板

  1. 请参照下载的模板格式，将您导出的合同数据逐一填写到模板中

  2. 请确保所有必填字段完整，且数据格式（如日期格式）符合模板要求

  3. 核心字段说明：

字段 含义 必填校验 参考示例
storeHandle SHOPLINE 店铺 handle 必填 stgyangcheng2
id_processed 第三方合同号 必填 1111111
status 合同状态：ACTIVE，CANCELLED，FAILED，EXPIRED （缺少暂停） 必填 ACTIVE
interval 订阅的时间间隔周期（DAY, MONTH, WEEK, YEAR） 必填 DAY
interval_count 间隔数量，例如每3周购买一次，此处值为3 必填 2
max_cycles 最大执行周期。若没有值，则默认为无限期合同   12
min_cycles 最小执行周期 必填 2
periods 已履约订单数。若没有值，则默认为 0   4
processed_at 第三方合同创建时间   2024-12-02T12:00:00
next_billing_date 合同下一次执行时间【搬迁后的首次执行时间】 必填 2025-01-28T12:00:00
currency_code 币种信息 必填 MYR
line_items_amount 商品的售价，商品折扣前的价格 必填 100
line_items_variant_id SHOPLINE 商品唯一 SKU ID 必填 18066984575317893633362795
line_items_product_source 商品 SKU 来源    
line_items_quantity 商品数量，要大于0，最大限制99999 必填 2
line_items_adjustment_type 折扣类型，例如百分比（PERCENTAGE），固定金额（FIXED_AMOUNT）   FIXED_AMOUNT
line_items_adjustment_value 折扣值   20
customer_id 订阅客户 SHOPLINE Customer ID 必填 4603168091
email 订阅客户邮箱   xuweihang@shopline.com
delivery_first_name 名   bing
delivery_last_name 姓   tang
delivery_name 昵称    
delivery_phone 联系电话   13123334444
delivery_country 国家或是地区名称   United States
delivery_country_code 国家或是地区编码，两位的编码缩写（ISO-3166-1），由SL转码 必填 US
delivery_province 州或是省名称   Ohio
delivery_province_code 州或是省编码，传入标准码（ISO-3166-2），由SL转码 必填 WA
delivery_city 城市名称   Cleveland
delivery_city_code 城市编码    
delivery_company 公司名称   FireXuan-USD
delivery_district 行政区名称    
delivery_district_code 行政区编码   94101
delivery_address1 详细地址信息1，用作补充信息   University Hospital Drive
delivery_address2 详细地址信息2，用作补充信息   RR 2 Box 260
delivery_zip 收货地址邮政编号   44106
delivery_id SHOPLINE 物流计划名称   Multi Delivery Test Plan
delivery_amount 物流价格   50
selling_plan_id 订阅计划ID，来源为 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    

根据支付渠道类型拆分合同

SHOPLINE 目前支持以下三种支付渠道的订阅支付：

  • SHOPLINE Payment

  • Stripe

  • Paypal

若您客户的合同在原平台绑定的是以上三种支付渠道之一，则可以将对应支付方式的合同单独拆分为独立的 CSV 文件。在导入时，若选择的支付渠道为 SHOPLINE Payment、Stripe、Paypal 中的一种，合同将会在导入后就绑定支付方式，并直接完成迁移。
Group 3558309.png

导入 CSV 文件

  1. 回到 SHOPLINE 订阅电商插件后台

  2. 在导入弹窗中点击【下一步】

  3. 将填写好的 CSV 文件拖拽或点击上传至指定区域

  4. 选择合同对应的支付渠道

  5. 点击【导入】，等待合同导入完成
    image 40.png

 

 

导入任务状态与导入结果查询

无论您采用 CSV导入 还是 API 同步，您都需要了解如何查看和管理导入/同步结果。

任务进度与状态展示

当您点击【立即导入】后，系统后台会开始一个导入进程。关闭导入的弹窗，导入任务也会继续进行。

注意：同一时间内仅能有一个导入任务在后台进行，在导入完成之前您无法开启一次新的导入任务。

导入任务完成后，会有三种状态

  • 导入成功：通过 Recharge API 获取的或您通过 CSV 上传的所有合同都已完成导入

  • 导入部分成功：存在部分合同的未能成功导入，可能的原因有数据不匹配、格式不符合等，可以通过下载结果文件获取导入失败的原因

  • 导入失败：没有合同成功导入，可以通过下载结果文件获取导入失败的原因

下载结果文件

  • 导入任务完成后，若任务执行结果为「导入部分完成」或「导入失败」，您可以点击【下载】按钮，下载导入结果文件

  • 结果文件（CSV格式）将包含合同 ID，以及「失败原因」，明确指出某行合同数据导入失败的详细失败原因

  • 您可以根据失败原因，修正原始 CSV 文件中的数据后重新上传，以完成剩余合同的导入

 

 

搬迁合同管理

在此将介绍搬迁合同在 SHOPLINE 后台的展示和管理方式，以及不同「迁移阶段」的含义。

迁移合同列表与迁移阶段

登录 SHOPLINE 订阅电商插件后台，进入订阅合同页面，点击【查看迁移合同】按钮，进入迁移合同页

迁移合同数据报表

迁移合同页会提供三个关键数据的指标，数据口径如下：

  • 总迁移合同数：当前迁移合同列表中的合同总数

  • 迁移成功合同数：迁移状态为「迁移成功」的合同总数

  • 待更新支付方式合同数：合同状态为「生效中」或「已暂停」，且迁移状态为「待更新支付方式」的合同总数

迁移合同列表

迁移合同列表将展示所有已导入/同步的搬迁合同。涉及合同迁移的核心字段如下

字段名 字段定义 字段值枚举 字段值定义
迁移方式 当前合同的导入方式 CSV 导入 合同是通过 CSV 导入的
Recharge API 合同是通过 Recharge API 自动同步的
Appstle API 合同是通过 Appstle API 自动同步的
Loop API 合同是通过 Loop API 自动同步的
Seal API 合同是通过 Seal API 自动同步的
迁移完成时间 合同状态更新为“迁移成功”的时间点 具体时间点 合同状态更新为「迁移成功」的时间点
迁移状态 当前合同是否已由 SHOPLINE 接管，并完成支付方式更新 待更新支付方式 客户还未完成当前合同的更新操作，合同仍在原平台运行
迁移成功 客户已更新当前合同，合同已被 SHOPLINE 接管，需要前往原平台取消合同
无需迁移 原平台合为「Cancelled」、「Failed」或「Completed」状态，视作合同无需迁移

筛选功能

筛选功能： 您可以使用顶部的筛选条件，快速筛选出想要的合同。筛选项如下：

  • 迁移状态：待更新支付方式、迁移成功

  • 原平台合同状态：生效中、已暂停、已取消、已到期

  • 迁移方式：Recharge API、CSV

  • 迁移完成时间：可选择指定范围的日期

召回客户操作

为了鼓励客户尽快完成支付方式更新，将「待更新支付方式」合同转为「迁移成功」，您可以利用自动邮件功能：

  • 筛选合同列表：通过合同列表的筛选功能，筛选合同

    • 迁移状态为「待更新支付方式」

    • 平台合同状态为「生效中」或「已暂停」
      Group 3558310.png

  • 召回方式选择： 弹窗将提供两种召回方式：

    • 自动发送召回邮件： 系统将对筛选出合同对应的客户发送预设的召回邮件。您可以编辑模板内容，召回链接将直接指向客户的合同管理后台。

    • 导出合同及用户列表至邮箱： 您可以选择导出当前选择的合同列表至您的指定邮箱，以便您进行自定义的营销活动或人工跟进。
      image 42.png

注意：在召回客户之前，请确保您已完成合同迁移通知设置，以便客户能够感知清晰的信息。详细配置请参考 合同迁移通知设置

 

 

客户端激活流程介绍

在此向您介绍客户如何通过更新支付方式来将「待更新支付方式」合同最终转换为「迁移成功」状态。

合同迁移通知设置

合同迁移过程中，客户无法编辑订阅合同，请开启订阅合同的「提示更新通知横幅」，并结合运营策略提示客户更新支付方式，完成合同迁移后客户可正常编辑合同。您可以在订阅电商 > 店铺展示设置 > 合同迁移通知找到相关配置。
image 43.png

客户操作路径

若客户希望修改合同的状态，或是进行合同编辑，他必须先完成合同升级。具体的操作路径如下：

  1. 登录客户中心：客户登录其在您店铺的个人中心，进入我的订阅页面。
    Group 3558302.png
    Group 3558303.png
  2. 触发换绑提醒： 当客户期望对一份「待更新支付方式」的合同进行操作时（如：调整履约计划、更改收货地址等），系统会弹出一个提示框，引导客户更新支付方式。
  3. 合同升级向导：客户点击【立即更新】后，会进入一个「合同升级向导」弹窗，清晰展示合同信息并允许其修改：
    • 下次履约日期。
    • 收货地址。
  4. 更新支付方式：客户确认合同信息无误后，会进入支付绑定流程，在此绑定新的支付方式。
    Group 3558304.png
  5. 完成与确认：支付方式绑定成功后，页面会提示确认信息。客户确认后，系统将进行最终检测。若更新成功，原「待更新支付方式」的合同将刷新为「迁移成功」状态。

商家收到的通知

当客户成功完成支付方式更新，将其「待更新支付方式」合同激活为「迁移成功」时，您会收到一封邮件通知。

  • 通知内容：【重要操作】您的客户（[客户邮箱]）原订阅合同（[原合同 ID]）已由 SHOPLINE 接管。为避免重复扣款，请您务必登录原订阅平台，手动取消对应的旧合同。

 

 

数据维护与更新

了解合同数据在我方系统中的更新机制，确保信息的准确性。

API 自动更新

  • 如果您已启用 API 自动化同步，则来自 Recharge 的合同数据变更（如合同续期、状态变更等）将通过 Webhook 机制准实时地自动同步到 SHOPLINE 的迁移合同列表中

  • 您无需进行任何手动操作来更新这些「待更新支付方式」合同的快照信息

CSV 手动更新

  • 如果您采用 CSV 导入方案，且「待更新支付方式」合同在原平台发生数据变更，您可以手动更新 SHOPLINE 中的快照信息。

  • 操作流程：

    1. 从原平台导出最新的合同数据。

    2. 准备一份包含需要更新的「未接管」合同的 CSV 文件，确保 external_contract_id 不变，但其余字段使用最新值。

    3. 按照 CSV 导入准备 的步骤，重新上传这份 CSV 文件。系统将根据 external_contract_id 识别并更新已有的合同快照。

 

 

常见问题 (FAQ)

商家在使用双系统搬迁方案过程中可能遇到的常见问题及其解答

Q1：为什么我导入的合同都是「待更新支付方式」状态？

这通常是因为合同的原支付方式（如Shopify Payment）目前不受 SHOPLINE 支持，或者合同的支付方式尚未完成迁移。

Q2：如何让「待更新支付方式」合同变为「迁移成功」？

对于所有「待更新支付方式」合同，客户端可主动更新支付方式。

Q3：我需要手动在原平台取消合同吗？

如果您通过 CSV 导入合同，当合同被 SHOPLINE 标记为「迁移成功」后，为避免重复扣款，您必须手动登录原订阅平台，取消对应的旧合同。如果您通过 Recharge API 导入合同，当合同被 SHOPLINE 标记为「迁移成功」后，会自动调用 Recharge API 将原平台的旧合同取消。

Q4：API 同步后，Recharge 的订单数据会同步到 SHOPLINE 吗？

目前，API 同步主要关注合同数据快照的更新。订单数据需要您通过多平台店铺一键搬迁插件手动同步。