Global Catalog REST 已停，离线 Token 明年强制过期

11 月 2 日起，Global Catalog REST API 不再服务任何流量。discover.shopifyapps.com/global/... 的全部请求直接失败，包括查询保存过的 catalog。4 月份 deprecated 时官方就给了替代品 Global Catalog MCP，半年窗口用完了。

另一头在明年。10 月 27 日，Shopify 把离线 Token 的执法时间线写死：2027 年 1 月 1 日未迁移的 public app 下架，4 月 1 日起旧 Token 返回 HTTP 403。两件事都要动代码，一件今天就是急的，另一件还有两个月，别当成不急。

昨天开始挂的那个接口

Global Catalog REST API 在 2026 年 4 月被标记 deprecated，替代者 Global Catalog MCP 实现的是 Universal Commerce Protocol（UCP）。11 月 2 日之后，四个端点全部停止服务：

• GET /global/v2/search
• GET /global/v2/p/{upid}
• GET /global/v2/p/by-variant/{vid}
• POST /global/v2/lookup

受影响最直接的是做跨店聚合的 App。比如一家做宠物用品比价的团队，选品工具里存了两百个监控商品，每晚定时用 /global/v2/lookup 批量拉最新价格，早上给用户出比价报表。11 月 2 日之后，这个任务的第一条请求就失败，报表空窗，商家当天就能发现价格不动了。比价、全网搜索、跨店找货，依赖这个目录接口的功能在同一天失去数据源。

保存过的 catalog 也一样挂。停服后有没有缓冲、旧地址会不会重定向，官方没写清，changelog 只有 stops serving traffic 一句。我按没有缓冲处理，调度任务还在打这个域名的，现在就该收到报警。

换法

核心是把四个 REST 调用换成三个 UCP 工具，发到 https://catalog.shopify.com/api/ucp/mcp：

• 搜索 → search_catalog，支持过滤、分页、buyer context
• 单品和变体 → get_product，标识符传 gid://shopify/p/{upid} 或 gid://shopify/ProductVariant/{id}
• 批量 → lookup_catalog，一次最多 50 个

两个容易漏的细节：每个请求要带 meta.ucp-agent.profile，值是 agent profile URL；查保存过的 catalog 改传 catalog.catalog_id，别再拼旧端点 URL。

认证方式不变，还是 Dev Dashboard 的 client credentials 换 bearer token。

想先试再改，用 UCP CLI 跑一条 ucp catalog search，CLI 在 github.com/Shopify/ucp-cli。UCP 在真实流量里的报错形态我还没试过，这块说不准，先在测试环境跑通再切生产。

changelog：https://shopify.dev/changelog/posts/global-catalog-rest-api-stops-serving-traffic-on-november-2-2026

Token 的三个日期，只有 1 月 1 日是你必须动的

这件事从年初开始铺垫：2026 年 4 月 1 日起新建 public app 已强制 expiring token，5 月 20 日 changelog 把范围扩展到全部 public app。当时只给了 1 月 1 日，10 月 27 日官方把逾期时间线补全：

• 2027 年 1 月 1 日：未迁移的 App 从 App Store 下架、禁止新装，存量安装继续工作。
• 2027 年 1 月 15 日：商家在 Shopify admin 看到警告。
• 2027 年 4 月 1 日：非过期 offline token 的 Admin API 请求返回 HTTP 403。

官方的说法很直接：1 月 1 日是迁移截止，后面两个日期是给商家的缓冲，不是给你的延期。代码要在 12 月 31 日前改完。

为什么收这么紧，官方的理由是泄露半径。非过期 token 一旦泄露永久有效，攻击窗口没有上限；expiring token 60 分钟过期并自动轮换，影响被压到一个小时内。范围要说清楚：受影响的是调 Admin API 的 public app，custom app、商家自建的 app、online access token 都不在名单里。很多团队把内部工具顺手做成 public app 上架，这部分最容易被忽略，值得先自查一遍再动手。

迁移比想象中轻。商家不用重装，代码里 exchange 现有 token 就能切换；官方模板和 API 库已实现 refresh，要自己做的只有 token exchange 和存储更新。指南：https://shopify.dev/docs/apps/build/authentication-authorization/migrate-to-expiring-offline-access-tokens

10 月底还有个实用兜底：client credentials access。以前 refresh token 丢了只能等商家重开 App，现在后端可以用 app 私钥签名直接换新 access token。对装了上千家店的老 App，这个兜底值回迁移成本。

顺手

同一条公告还给了两个低成本开关：shopify.app.toml 新增 [network_access] 段，声明 App 访问的服务器和站点；Dev Dashboard 支持 IP allowlist。发布前跑一遍 shopify app security check。

排期

还在调 REST 的没有排期可言，接口已经死了，今天就是迁移日。用非过期 token 的把迁移排进 Q4，别拖到 1 月商家开始看到警告、支持工单找上门才动。