Google Merchant API 架构指南：替代 Content API for Shopping、2026 年停用时间表与模块化升级方案

Google Merchant API 架构指南：替代 Content API for Shopping、2026 年停用时间表与模块化升级方案

系列文章导航

围绕 Google 开发者文档兼容性专栏（Compatibility with Content API for Shopping）的四个模块，我们在 Google 数字营销与商品流工程专栏整理了四篇迁移指南，供研发与投放团队按顺序查阅：

1. 系列一（本文）：《Google Merchant API 架构指南：替代 Content API for Shopping、2026 年停用时间表与模块化升级方案》
2. 系列二：《Google Merchant API 迁移实战手册（Start Your Migration）：子 API 优先级排期、ProductInput 读写分离与防“Offer Stealing”指南》
3. 系列三：《Google Merchant API 认证与 GCP 项目架构指南：取消 GMC 后台直接发证、registerGcp 开发者注册与零停机切换》
4. 系列四：《Google Merchant API 高并发代码重构实战：移除 custombatch、优化 gRPC 100 并发流上限与动态配额管理》

第一章：2026 年～2027 年官方停用时间表与受影响范围自查

排定研发工期前，需先确认旧接口的断流节点，以及哪些业务集成需要自行修改代码。

1.1 官方四个停用节点（Deprecation & Sunset Timeline）

第二章：模块化子 API 架构与 URL 寻址变更

旧版 Content API for Shopping 将账号权限、商品写入、Feed 规则、促销活动、本地门店库存与报表查询耦合在单一的 v2.1 版本空间下。任一边缘接口升级，都会牵动整个 SDK 版本变更。

Merchant API 遵循 Google Cloud AIP（API Improvement Proposals）工程规范，将其拆分为十余个彼此解耦、拥有独立版本号（v1 或 v1beta）的子 API（Sub-APIs）。

2.1 URL 寻址格式对比与子 API 列表

• 旧版 Content API v2.1 请求格式： https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/{RESOURCE}/{ID}
• 新版 Merchant API v1 请求格式： https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}

第三章：易引发 400 报错的三项资源编码规则

代码迁移时，首次联调失败大多源于沿用了旧版 ID 拼接方式。你可以在下方交互式转换器中切换商品写入、单品状态读取、MCQL 报表查询和 GCP 注册四类场景，对比新旧 URL 与 JSON 请求体差异，并测试特殊 SKU 的编码结果：

POST https://shoppingcontent.googleapis.com/content/v2.1/4321009/products
Content-Type: application/json

{
  "offerId": "SKU-2026-PRO",
  "contentLanguage": "en",
  "targetCountry": "US",
  "channel": "online",
  "title": "Flagship Wireless Earbuds",
  "price": {
    "value": "33.45",
    "currency": "USD"
  }
}

POST https://merchantapi.googleapis.com/products/v1/accounts/4321009/productInputs:insert?dataSource=accounts/4321009/dataSources/987654
Content-Type: application/json

{
  "offerId": "SKU-2026-PRO",
  "contentLanguage": "en",
  "feedLabel": "US",
  "productAttributes": {
    "title": "Flagship Wireless Earbuds",
    "price": {
      "amountMicros": "33450000",
      "currencyCode": "USD"
    }
  }
}

3.1 层次化资源标识符 name 与父资源 parent（AIP-122）

• 旧版 Content API 需要在路径参数中分别传入 merchantId 和 productId。而在 Merchant API 中，每个资源都有全局唯一的层次化路径 name（例如 accounts/123456789/products/en~US~SKU-9001）。
• 创建或列出子资源时，统一传入父容器路径 parent（例如 parent = "accounts/123456789"）。

3.2 商品复合键移除 channel，分隔符由冒号 : 改为波浪号 ~

• 旧版复合 ID（4 段冒号分隔）：online:en:US:SKU-9001 或 local:en:US:SKU-9001
• 新版复合 ID（3 段波浪号分隔）：en~US~SKU-9001（固定格式为 {contentLanguage}~{feedLabel}~{offerId}）。
  • 移除 channel 的原因：新版 Merchant Center Next 已合并线上与线下商品模型，不再在主键中固定写入 online 或 local（历史纯线下门店 Feed 的兼容过渡规则，详见系列二迁移实战手册中的 legacyLocal 说明）。
  • 区分 feedLabel 与 targetCountries：主键中间段使用的是大写的两字母或自定义数据源标签 feedLabel（如 US 或 US-PROMO），并非投放国家列表。

3.3 含特殊符号的商品键须执行无填充 RFC 4648 base64url 编码

跨境服饰、汽配与多变体卖家的 SKU 常带有特殊符号。Google 官方规定，只要完整商品键（contentLanguage~feedLabel~offerId）包含以下任一保留字符，就必须进行编码：

• 触发强制编码的字符集：%、.、+、/、:、两个及以上波浪号 ~（即 offerId 自身含有 ~）、,、(、*、!、)、&、?、=、@、#、$。
• 编码方法：请将整串 contentLanguage~feedLabel~offerId 转换为 RFC 4648 Section 5 标准的 base64url 字符串，且不得保留末尾的 = 填充符（Unpadded）。注意要对整串字符编码，不要只编码 offerId。
  • 错误写法（返回 400 或 404）：accounts/123456/products/en~US~TEE/BLK+XL#1
  • 正确写法（全串无填充 base64url）：将 en~US~TEE/BLK+XL#1 编码为 ZW5-VVN-VEVFL0JMSytYTCMy（将标准 base64 中的 + 替换为 -，/ 替换为 _，并去掉末尾 =），请求 accounts/123456/products/ZW5-VVN-VEVFL0JMSytYTCMy 即可正常访问。

第四章：数据类型、传输协议与新增功能对比

除 URL 和主键调整外，Merchant API 在数值精度、传输吞吐量与状态订阅机制上也有多项变更：

第五章：AI Agent 配套接口：官方 MCP Server 与 UCP 代理商业报表

Google 将新一代 AI 代理商业（Agentic Commerce）接口全部建立在 Merchant API 之上，旧版 Content API 不支持以下两项功能。

5.1 官方托管 Merchant API MCP Server

Google 在开发者文档中推出了基于开放协议的远程 Merchant API MCP Server（端点地址为 https://merchantapi.googleapis.com/mcp，目前处于 Alpha 预览阶段）：

• 运行方式：研发或运营 Agent（如 Gemini CLI、Claude Code 或自研巡检 Agent）无需手写 REST 封装代码。启用 merchantapi.googleapis.com 并配置 OAuth 凭证后，连接该 MCP 端点即可用自然语言调用 GMC 工具，完成商品查询、拒登排查、库存核对与报表分析。
• 工程应用：你可将该官方 MCP 接口与《SEO 与 GEO 实战手册》中的自动化审计流程结合，搭建每日巡检 GMC 拒登并自动生成修复补丁的运营工具。

5.2 新增 ucp_agentic_performance_view 代理商业成效视图

此前在 Google AI Mode、Gemini 购物助手与通用商业协议（UCP）场景下，卖家难以统计商品在对话式 AI 助手中的推荐次数（相关机制详见《Google UCP 代理式商业与 Shopify 原生结账指南》与《Google Ads AI 搜索体验广告实战指南》）。

新版 Merchant API reports/v1 新增了 ucp_agentic_performance_view 视图，支持通过 MCQL 语句按日期、offer_id 和展示渠道拉取 AI 代理推荐的曝光与点击数据：

这一报表可配合 OpenAI 的 Businesses in ChatGPT 28 天搜索洞察与 Shopify 直连使用，帮助商家量化实时商品流在 AI 购物渠道的曝光与点击。

第六章：下一步迁移准备

了解整体架构与 2026 年 8 月 18 日停用节点后，请勿直接修改线上商品写入代码。Google 官方要求按模块先后顺序逐步迁移，避免引发数据源归属错位（Offer Stealing）故障。

下一步请阅读系列第二篇：《Google Merchant API 迁移实战手册（Start Your Migration）：子 API 优先级排期、ProductInput 读写分离与防“Offer Stealing”指南》，继续了解四步迁移排期、ProductInput 与 Product 读写分离重构及 MCQL 报表语法变更。