核心要点
– 10 月 27 日两项 Catalog 更新
– 新增 sources 参数，可搜站外品牌商品
– 外部商品 native_checkout 恒为 false
– 基础佣金 0.3%，外部商品不参与分佣
– 11 月 2 日老接口停用，无宽限期
Shopify 同一个礼拜放了两条消息，一条开闸，一条断路。
10 月 27 日，Shopify 在开发者更新日志里连发两条 Catalog 更新。一条是 search_catalog 新增 sources 参数，AI 应用可以检索不在 Shopify 建站的外部品牌商品。另一条是 Shop Campaigns 商户出资的佣金接进了 Promoted Placements。
另一件事时间更紧。Global Catalog REST API 将于 11 月 2 日停止服务，指向 discover.shopifyapps.com/global 的请求会直接失败，官方没给宽限期。
sources 参数：搜什么由开发者决定
按 Shopify 更新日志，Catalog API beta 版的 search_catalog 现在接受一个 sources 参数。取值有三种。
不传这个参数，或者传 ["shopify"]，返回的还是 Shopify 商户商品。传 ["shopify", "external"]，两类商品在同一个结果里排在一起。传 ["external"]，只搜不在 Shopify 建店的品牌。
这个参数直接挂在已有的 search_catalog 方法上，不新增端点。现有调用不传参数，行为完全不变。
get_product 传入外部商品 ID 时会返回该外部商品。lookup_catalog 的支持还在后面的路上，官方写的是即将推出。
外部商品包含 description、image、price，以及一条指向品牌商品页的 link，买家在品牌自己的网站完成购买。
| sources 取值 | 返回内容 | 现有调用要不要改 |
|---|---|---|
省略或 ["shopify"] |
只有 Shopify 商户商品 | 不用改 |
["shopify", "external"] |
两类商品排在一起 | 要改 |
["external"] |
只有站外品牌商品 | 要改 |
外部商品：能搜到，不能买
限制条件写在更新日志里，一共三道。
第一，功能处于 Beta。Beta 期间外部商品数据来自各品牌官网，Shopify 不做校验。
第二，只有买家在美国时才返回外部商品。面向其他国家消费者的搜索，仍旧只返回 Shopify 商户商品。官方文档写得更直接，外部报价目前覆盖的是向美国销售商品的商家。
第三，也是最关键的一条，外部商品永远返回 eligible.native_checkout: false。买家不能通过 Shopify 结账购买，这些商品也不赚 Promoted Placements 佣金。
还有一条容易被忽略的硬约束。使用外部商品的应用不得为它创建购物车、结账或支付流程，不得把 Shop Pay 或 Shopify 结账展示成可用选项。展示时必须标明 seller.name，并给出指向品牌官网页面的链接。
这条规则的实际含义是：你能把别人的商品放进自己的 AI 界面当推荐位，但只能把人送过去，钱不能过你的手。
商品数据质量这层风险也是应用方自己扛。外部商品的价格是刷新时观察到的值，可能缺失，只作参考。库存不追踪，available 字段只要商品在架就是 true，不代表真现货。
这一点对做 AI 购物助手的开发者尤其要紧。商品数据能不能被代理读懂，直接决定推荐准不准，可读性自检清单可以看Shopify 商品数据可读性四项自检。
佣金怎么分：0.3% 打底
Promoted Placements 这条线也更新了。
按 Shopify 官方文档，基础佣金是符合条件归因购买金额的 0.3%，也就是 30 个基点。开发者要接入的话，先在保存的 catalog 上打开 Earn commission，再在 search_catalog 调用时带上 catalog.catalog_id。这个能力是邀请制，处在 Developer Preview 阶段。
这次更新把 Shop Campaigns 纳进来了。运行着面向外部平台 Shop Campaigns 的商户，Catalog API 现在算作这些平台之一。这些商品上，placement.commission.percentage.value 返回的是总费率，也就是 Shopify 基础费率加上商户自己掏的那部分。
边界写得很清楚。商户出资的额外佣金只适用于符合条件的 Shopify 商户商品，而且消费者必须走指定的 Shopify 购买路径成交，也就是在 Shop 手机应用或 shop.com 里下单。如果消费者在商户官网或嵌入式结账里买，那笔成交只能拿到基础费率。
归因窗口是 7 天，用最后一次非直接点击归因。订单里的每一件符合条件的商品都计佣，不只是消费者点进去的那个变体。
费率现在因商品而异，别写死，要从 placement.commission.percentage.value 里读。
11 月 2 日，老接口直接断
这是本篇最该马上看的一段。
Shopify 4 月弃用了 Global Catalog REST API，11 月 2 日起这个 API 停止服务。之后所有指向 discover.shopifyapps.com/global/... 的请求都会失败，包括走 saved catalog 的请求。官方公告没有给宽限期，也没有把老请求自动转发到新接口的兜底安排。
下线的四个端点是 GET /global/v2/search、GET /global/v2/p/{upid}、GET /global/v2/p/by-variant/{vid} 和 POST /global/v2/lookup。
替代方案是 Global Catalog MCP，端点 https://catalog.shopify.com/api/ucp/mcp，基于 Shopify 的 Universal Commerce Protocol。迁移不是改成 GraphQL，是 REST 调用换成对应的 MCP 工具。
| 旧 REST 调用 | 新 MCP 工具 | 变化要点 |
|---|---|---|
/global/v2/search |
search_catalog |
支持全文查询、过滤、分页与买家上下文 |
/global/v2/p/{upid} |
get_product |
UPID 要转成 gid://shopify/p/{upid} |
/global/v2/p/by-variant/{vid} |
get_product |
变体要转成 gid://shopify/ProductVariant/{id} |
/global/v2/lookup |
lookup_catalog |
单次最多 50 个标识符 |
还有三处容易漏。每个请求都要带 meta.ucp-agent.profile，填你公开托管的 agent profile JSON 地址。saved catalog 不再用 URL 传，改成在请求体的 catalog.catalog_id 里传 ID。认证方式不变，Dev Dashboard client credentials 领的 bearer token 照样能用。测试可以用 Shopify AI Toolkit，或者跑 ucp catalog search 用 UCP CLI。
这里有个把两条消息串起来的关键点。sources 参数是加在 MCP 侧的 search_catalog 上的，老 REST 的 /global/v2/search 没有这个参数。想用站外品牌商品这条新流量线，Agent 就必须已经跑在 MCP 上。
10 月 13 日那次开放十亿商品目录，商家还没有开关可关，那次讲的是渠道选择权转移，详见Shopify 十亿商品目录开放与商家没有开关可关。这次讲的是两笔账：钱怎么分，接口什么时候断。
你现在该做什么
四件事，按紧急程度排。
第一，今天就查你的 Agent 还挂在哪个接口上。11 月 2 日一到，老接口直接失败，没有过渡期。官方公告只给了一个终点日期，没说提前多久切换就算安全，迁移指南建议留出数周缓冲，最晚 8 月或 9 月就动手，并把回滚方案写成文档。
第二，迁移期间保留 fallback，用 feature flag 控制新旧路径切换，灰度阶段盯住错误率、延迟和结果差异。
第三，核对后台里 Shop Campaigns 的状态。开了面向外部平台的 Shop Campaigns，你的商品才可能拿到高于 0.3% 的费率。这件事商家自己做，不用等 AI 应用来谈。
第四，把商品数据的结构化字段补齐。Shopify 的推断属性自己都承认可能不准，尺寸、材质、颜色、发货地填得越准，越容易被选上。
同一套 AI 投放逻辑在别处也在铺开，比如 Meta 把代理 AI 直接放进了 Ads Manager，素材规范和审批边界是另一套玩法，Meta 代理 AI 接管 Ads Manager 要点 可以对照看。
参考文章
- 《Search brands that don’t sell on Shopify in the Catalog API (beta)》｜Shopify Developer Changelog｜https://shopify.dev/changelog/posts/search-brands-that-don-t-sell-on-shopify-in-the-catalog-api-beta
- 《Global Catalog REST API stops serving traffic on November 2, 2026》｜Shopify Developer Changelog｜https://shopify.dev/changelog/posts/global-catalog-rest-api-stops-serving-traffic-on-november-2-2026
- 《Promoted Placements beta now includes Shop Campaigns》｜Shopify Developer Changelog｜https://shopify.dev/changelog/posts/promoted-placements-beta-now-includes-shop-campaigns
- 《Earn with promoted placements》｜Shopify Developer Docs｜https://shopify.dev/docs/agents/catalog/promoted-placement
- 《Global Catalog extension》｜Shopify Developer Docs｜https://shopify.dev/docs/agents/catalog/global-catalog-extension
- 《Shopify将站外品牌纳入AI商品目录，Google与ServiceNow打通零售Agent》｜腾讯网｜https://new.qq.com/rain/a/20261028A02T0X00
FAQ
站外品牌商品能被放进购物车吗？
不能。Shopify 文档写明，不得为外部商品创建购物车、结账或支付流程。eligible.native_checkout 恒为 false，checkout_url 不存在。购物车只能建在品牌自己的官网上。
开发者搜到站外商品，能拿到佣金吗？
拿不到。外部商品永远不带 placement 对象，也不赚 Promoted Placements 佣金。佣金只对 Shopify 商户商品生效，站外品牌不在这个计划里。
佣金 0.3% 之外还能加吗？
能，但有条件。商户开了面向外部平台的 Shop Campaigns 时，Catalog API 算作投放平台之一，可以在 0.3% 基础上叠加商户出资的部分。但消费者必须在 Shop 手机应用或 shop.com 完成下单，在商户官网成交只能拿基础费率。
11 月 2 日之后老接口还能用吗？
不能。公告写的是老接口停止服务，指向 discover.shopifyapps.com/global 的请求会失败，没有宽限期，也没有自动转发到 MCP 的兜底。认证方式倒是没变，Dev Dashboard 的 bearer token 迁到 MCP 后照常使用。
原创文章，作者：跨境头条编辑部，如若转载，请注明出处：https://www.tokenfff.com/shopify-catalog-external-brands-2026/
