结账与订单页面链接格式更新适配指引 – SHOPLINE 常见问题

结账页面与订单状态页面的链接格式即将进行调整：链接中的店铺 ID（storeId）部分将从路径中移除，让结账与下单流程使用更独立的资源路径，不再与店铺其他页面共享同一套访问资源，从而降低大促高峰期或店铺其他页面出现异常时对结账流程的影响。

SHOPLINE 将于 2026 年 9 月 19 日 对所有店铺的结账与订单页面链接进行全量切换，切换完成后将无法回退至历史格式。多数店铺无需进行任何操作；只有在【自定义代码插件】、【主题模板开发】、【应用】、【301重定向配置】、【开放接口】或【第三方系统】中解析或依赖了旧链接路径时，你或你的技术服务商才需要参考本文完成技术适配。

重要： 买家的正常访问、下单与页面跳转体验不会受到影响；历史格式的链接会自动跳转至新链接，你不需要手动更新任何已发送出去的链接。

1. 链接格式更新带来的好处

本次结账链接改造将让结账与订单页面使用更稳定的专属链路，与普通店面页面的流量和故障相互隔离。即使在大促高峰或店面页面出现异常时，结账页仍能获得独立保障，帮助买家更顺畅地完成支付，降低下单中断和订单流失风险。同时，历史链接会通过跳转继续可用，商家已发送的营销邮件、弃单召回及订单链接无需担心立即失效。

2. 格式更新带来的影响

本次更新适用于所有店铺的结账页面与订单状态页面链接。链接中原本包含的店铺 ID 部分将从路径中移除，只保留结账或订单所需的核心信息。例如，结账页面的链接格式将由：

变更前：

https://{store domain}/1234567890/checkouts/{checkoutToken}
                      └────┬────┘

                     storeId，本次移除

变更後：

https://{store domain}/checkouts/{checkoutToken}

订单状态页面的链接也会采用相同的调整方式，移除路径中的店铺 ID 部分。

是否需要适配，取决于你的代码如何使用这些链接，而不是它涉及哪个页面：

需要适配：你的代码会从这些页面的 URL 里解析内容，比如判断页面类型、提取 storeId、提取 checkoutToken。这类代码在变更后可能取到错误的值。
无需改动：你只是接收平台给出的完整链接并直接跳转，不在链接上做任何解析。这类场景不受影响。

如果你的自定义代码、主题、应用、301 重定向或第三方集成属于以上「需要适配」的情况，请参考《4. 需要适配的场景》查看完整的分类说明。

3. 完整路径对照

下表列出每个页面变更前、变更后的路径格式。两列中除「本次不变更」外，全部是本次要改的内容。

页面	变更前	变更后
结账页（含结账页面）	`/:storeId/checkouts/:token`	`/checkouts/:token`
结账页（Thank you 页面）	`/:storeId/checkouts/:token/thank_you`	`/checkouts/:token/thank_you`
订单状态页	`/:storeId/orders/:orderSeq`	`/orders/:orderSeq`
Processing 页	`/:storeId/checkouts/:token/processing`	`/checkouts/:token/processing`
问题处理页	`/:storeId/checkouts/:token/stock_problems`	`/checkouts/:token/stock_problems`
限流页	`/:storeId/checkouts/:token/overload`	`/checkouts/:token/overload`
异常页（结账）	`/:storeId/checkouts/:token/error`	`/checkouts/:token/error`
异常页（订单）	`/:storeId/orders/:orderSeq/error`	`/orders/:orderSeq/error`
订阅换绑页	`/payment_methods/:token`	不含 storeId，本次不变更

需要 storeId 时如何获取：

店铺自定义代码：从平台注入的全局对象读取，如 window.Shopline.storeId（详见官方说明）。
开放平台应用：从应用安装上下文 / 接口返回值中获取 storeId 字段，具体接口能力见开放平台文档。

注意： 变更后，页面 URL 中的 storeId 段将被移除，不要从 URL 中解析 storeId。

4. 需要适配的场景

先看你的代码属于哪一类：开放平台应用，还是店铺自定义代码？对应下表逐条核对。

4.1. 开放平台应用

场景	是否受影响	处理方式
从页面 URL 判断“当前是不是结账页 / 订单状态页”	受影响	改用同时兼容新旧格式的匹配（见「4.4 代码示例：示例一」）
从页面 URL 提取 storeId	受影响	改从应用上下文 / 接口返回值获取，不要从 URL 解析（见「4.4 代码示例：示例二」）
从页面 URL 提取 checkoutToken / orderSeq	受影响	不要从 URL 提取。所需标识请通过开放平台提供的接口能力获取，详见开放平台文档；文档未覆盖的场景请提交开放平台工单
解析 Webhook / API 返回的 checkout_url 等 URL 字段，从中取值	受影响	该字段仅用于跳转，不要从中解析取值。需要 storeId、orderSeq 等字段时，请查阅开放平台文档获取对应接口能力；文档未覆盖的场景请提交开放平台工单
自行拼接结账 / 订单页链接	受影响	改用开放平台接口返回的完整 URL，不要自行拼接路径（见「4.4 代码示例：示例三」）
只是接收平台给的完整链接并跳转 / 展示	不受影响	无需改动
调用平台 OpenAPI 接口（/api/...）	不受影响	接口路径不在本次变更范围

4.2. 店铺自定义代码（自定义 JS / HTML）

场景	是否受影响	处理方式
用 location.pathname 判断页面类型，决定是否执行某段脚本	受影响	见「4.4 代码示例：示例一」
从 location.pathname 按下标取段（如 split('/')[1] 当作 storeId）	受影响	见「4.4 代码示例：示例二」。这是最容易被忽略的写法，变更后取到的值会变成 checkouts 而不报错
埋点 / 统计脚本按路径正则分组页面	受影响	见「4.4 代码示例：示例一」；同时请检查第三方统计后台（GA 等）里的页面分组规则
依赖路径的跳转逻辑、A/B 分流规则	受影响	见「4.4 代码示例：示例一」
纯样式的自定义 CSS	一般不受影响	若使用了基于 URL 的条件加载，按上述处理

4.3. 301重定向设置

路径：Admin-设置-域名-301重定向

场景	是否受影响	处理方式
【重定向自】包含 /:storeId/checkouts	受影响	新增新格式的匹配处理（见「4.4 代码示例：示例四」）
【重定向至】包含 /:storeId/checkouts	受影响	新增新格式的匹配处理（见「4.4 代码示例：示例四」）

4.4. 代码示例

示例一：判断页面类型

错误写法：

// 正则写死了开头的数字段，变更后会失效

if (/^\/\d+\/checkouts\//.test(location.pathname)) { /* ... */ }

if (location.pathname.split('/')[2] === 'checkouts') { /* ... */ }

正确写法：

// 只关心 checkouts 段本身，不关心它前面有没有东西，同时兼容新旧格式

const isCheckoutPage = /(^|\/)checkouts\/[^/]+/.test(location.pathname);

const isOrderPage    = /(^|\/)orders\/[^/]+/.test(location.pathname);

示例二：获取 storeId

错误写法：

// 变更后取到的是 "checkouts"，不报错但值是错的

const storeId = location.pathname.split('/')[1];

正确写法：

// 从平台注入的上下文获取（具体字段以平台运行时为准）

const storeId = window.Shopline?.storeId;



// 开放平台应用：使用应用安装上下文 / 接口返回中的 storeId 字段

示例三：生成链接

错误写法：

// 自行拼接路径（任何形式的手工拼接都不再适用）

const url = `https://${domain}/${storeId}/checkouts/${token}`;

正确写法：

// 使用开放平台接口返回的完整 URL，直接跳转

const url = response.checkoutUrl;

平台返回的链接始终是该店铺当前可用的格式，无需你判断切换状态。需要生成链接但现有接口未覆盖的场景，请查阅开放平台文档或提交开放平台工单。

注意： checkoutToken、orderSeq、storeId 等标识不要从 URL 中解析获取，请使用开放平台提供的接口能力。

示例四：301 重定向配置

原有配置：

// 原【重定向自】或【重定向至】配置

/示例 storeId/checkouts

新增配置：

// 新增新格式的对应配置

/checkouts

5. 自查清单

按下面三个步骤在自己的代码库里检索并逐条确认。每一条都确认完，才算完成自查。

第一步：检索关键词

checkouts        orders          thank_you       stock_problems

processing       overload        checkoutToken   orderSeq        storeId

第二步：检索模式（正则）

\/\d+\/checkouts        # 硬编码数字段 + checkouts

\/\d+\/orders           # 硬编码数字段 + orders

:storeId\/checkouts     # 路由模板写法

\{storeId\}\/checkouts  # 模板串写法

%s\/checkouts           # 后端格式化串写法

pathname.*split         # 按下标取路径段

pathname.*match         # 路径正则匹配

location\.pathname      # 所有对 pathname 的使用

第三步：逐条确认

所有页面类型判断已改为兼容新旧两种格式
不再从 URL 路径解析 storeId
不再从 URL 路径提取 checkoutToken / orderSeq
checkout_url 类字段仅用于跳转，不再从中解析取值
不再自行拼接结账 / 订单页路径，改用开放平台接口返回的完整 URL
第三方统计后台（GA 等）的页面分组、转化目标路径规则已同步

6. FAQ

Q1：旧链接会失效吗？

不会。历史格式的链接会持续自动跳转至新链接，长期可访问，你不需要手动替换任何已发送出去的链接，也无需迁移历史数据。

Q2：我的买家会感受到这次更新吗？

不会。买家的正常访问、下单与页面跳转体验不会受到影响，这项更新只涉及链接的技术结构。

Q3：如果我没有在截止日期前完成适配会怎样？

2026 年 9 月 19 日之后，链接格式将全量切换为新格式，且无法回退。如果你的自定义代码、应用或第三方系统仍依赖旧链接格式解析数据，可能会出现数据处理或功能异常（且往往是静默失效，不会报错或白屏），建议尽早自查并完成适配。

Q4：切换期间我会同时遇到两种格式吗？

会。按店铺分批切换，不同店铺、不同时间点格式可能不同。所以请按“同时兼容”适配，不要做非此即彼的判断。

Q5：我从接口拿到的链接，和店铺当前的切换状态不一致怎么办？

直接使用即可。平台返回的链接始终指向该店铺当前可用的页面，即使出现格式与切换状态不一致的情况，平台也会自动处理跳转，不会 404。

Q6：我需要 storeId、checkoutToken、orderSeq，但不能从 URL 取，怎么办？

请查阅开放平台文档中对应的接口能力；文档未覆盖的场景，请提交开放平台工单。

Q7：接口路径（OpenAPI）会变吗？

不会。本次仅变更买家侧页面链接，接口路径不变。

Q8：接口响应中的 checkoutUrl 会变吗？

会。会由历史的包含 storeId 变更为不含 storeId。

Q9：订阅换绑页会变吗？

不会。该页面路径本就不含 storeId。

7. 需要协助？

如果你已经确认受影响，但在适配过程中遇到接口未覆盖的场景，或对判断标准仍有疑问，请提交开放平台工单，或联系你的 SHOPLINE 客户经理获取协助。