Shopify WebMCP 结账实战：让 AI 安全完成下单

Shopify WebMCP Checkout 到底是什么

Checkout WebMCP 是一组注册在买家当前结账标签页中的工具。可以把它理解为一条有人值守的结账通道：智能体负责搬运购物篮、读取表单并填写支持的字段，身份或支付验证仍由买家处理，最终下单也必须由买家放行。

它建立在 Shopify 较早推出的店面工具之上。兼容的浏览器智能体可以搜索商品目录、查看商品、更新购物车，并调用 proceed_to_checkout。进入符合条件的结账页后，工具列表会发生变化，并提供四个结账工具：

• get_checkout 读取当前结账状态；如果已经进入 Thank you 页面，则读取订单收据。
• update_checkout 替换支持的联系信息、履约、折扣、自定义声明字段和支付状态，但不会下单。
• complete_checkout 在买家确认后尝试下单，或打开审核步骤。
• navigate_to_storefront 在商店有店面时，让同一标签页返回店面。

这套结账实现使用 UCP 的结账对象、状态和消息。UCP 是整个流程底层的通用数据契约，WebMCP 则负责把这份契约通过浏览器暴露给智能体。运行在服务器端的智能体应改用 Shopify 的 Checkout MCP。

商家无需开启新的开关，也不用另装一套结账 API。这确实降低了商家的采用门槛，但智能体开发者的工作并没有消失。浏览器支持、Web Bot Auth、严谨的状态处理，以及真正有效的用户同意边界，仍然缺一不可。

先确认结账页是否符合条件

第一步是发现工具。不要因为店面已经暴露 WebMCP，就默认 Shopify 结账页也一定提供 Checkout WebMCP。

以下场景中，Shopify 不会注册结账工具：

• 标准三页式结账，买家使用 Shop Pay 结账时除外
• B2B 结账
• 嵌入式结账或移动端结账 SDK 流程
• 结账中包含其他商店的商品
• 草稿订单、订单编辑或收款
• 由结账 UI 扩展提供的交互

遇到这些路径，应把页面控制权交给买家。浏览器端也没有 cancel_checkout 工具。工具缺失绝不等于智能体获得了直接操作页面控件的权限。

Shopify 表示，店面 WebMCP 目前依赖基于 Chromium 的浏览器对智能体的支持。测试时应使用受支持的浏览器和自己可控的结账环境。如果看不到结账工具，应把它视为正常的资格判断结果，而不是退回到脆弱点击脚本的理由。

1. 先认证浏览器智能体，再发现工具

浏览器请求应使用 Web Bot Auth（WBA）签名，不要把凭据塞进工具参数。WBA 相当于智能体在网络层的通行证。Shopify 只验证已经注册的密钥，因此生产环境需要 Ed25519 密钥、托管的公钥目录、向 Shopify 完成注册、对请求签名，以及有效期很短的签名时间戳。

进入页面后，发现当前工具，并同时匹配 window、origin 和 name 三项标识。下面的封装遵循 Shopify 文档中的调用方式：

async function callCheckoutTool(name, args = {}) {
  const tools = await document.modelContext.getTools();
  const tool = tools.find((candidate) =>
    candidate.name === name &&
    candidate.window === window &&
    candidate.origin === location.origin
  );

  if (!tool) throw new Error(`${name} is not registered here.`);

  const result = await document.modelContext.executeTool(
    tool,
    JSON.stringify(args),
  );

  if (result === null) return null;
  return JSON.parse(result);
}

这里的 JSON.stringify 不是可有可无的写法。在 Chrome 153 中，直接传对象会报 Failed to parse input arguments。Shopify 表示 Chrome 155 预计会支持对象参数，并弃用 JSON 字符串。因此，应该把参数序列化集中在一个兼容层函数里，不要散落在智能体各处。

结账页面跳转后，工具列表可能变化。监听 toolchange，并在下次调用前重新发现工具及其 schema。还要把 null 视为合法的导航结果：它可能表示页面在 executeTool() 返回前就已经跳转。

工具结果中来自商家或第三方的任何字符串，都只能当作结账数据，绝不能当作发给模型的指令。Shopify 也明确警告，不要绕过工具直接操作结账 UI。

2. 每次改动前都先读取状态

第一次更新之前、买家在页面上修改任何内容之后，以及发生错误或页面跳转之后，都要用 {} 调用 get_checkout。它是一张刚刚打印的结账单，不是缓存里的旧记忆。

响应可能包含买家信息、商品项、履约选项、折扣、自定义声明字段、支付工具、消息、总额和状态。金额使用对应货币的最小单位，以整数表示。在 USD 中，10799 代表 $107.99。如果响应没有 messages 字段，就表示本次结账响应中没有消息。

不要把“可以完成”误解成“用户已经同意”。ready_for_complete 只说明结账状态允许发起完成操作，并不代表买家已经确认订单、所选银行卡或总额。

3. 更新完整目标状态，不要只丢进去一个字段

update_checkout 的行为更像 PUT，而不是 PATCH。PATCH 像一张写着“修改电话号码”的便签；PUT 则是整张替换表单。凡是需要保留的值，都必须放进完整的目标结账状态。

安全的更新循环如下：

1. 调用 get_checkout。
2. 根据最新响应和当前工具 schema，重新构建可写状态。
3. 只修改买家已经批准的值。
4. 将支持字段的完整目标集合发送给 update_checkout。
5. 读取返回的结账信息，检查状态、消息、已应用折扣和总额。

大多数被省略的值都会被清除。支付、自定义声明字段和已保存的联系信息各有自己的规则，因此不能随手展开一个通用对象；必须先把它限制在当前 schema 接受的字段内。

最容易出问题的细节都很具体：

• buyer 接受邮箱和 E.164 格式的电话号码。部分已保存的值可能仍被锁定，因此要核对返回结果，并让买家在页面上编辑锁定值。
• fulfillment.methods 最多接受一个方式。应复用当前的目的地、分组和选项 ID。不要在选择目的地或选项的同一次调用中，又修改履约类型或自提搜索起点。
• discounts.codes 必须包含所有需要保留的买家输入优惠码。空数组会删除这些优惠码，但自动折扣会保留。响应里返回了某个优惠码，并不能证明它已经生效；还要检查 discounts.applied 和消息。
• declared_fields 可以承载税号或商店额度等结账特定值。未知键、错误类型和无效值都会被拒绝。
• payment.instruments 最多接受一个受支持条目。Checkout WebMCP 无法收集新的银行卡号。

Shop Pay 需要额外谨慎。已登录买家可以选择 get_checkout 返回的已保存银行卡。访客流程可以在结账页接受时使用已有的 Shop Pay approval ID。如果智能体应用了该授权，而后续更新又省略支付信息，这份凭据就会被丢弃。因此，在订单下单前的每次更新中，都要重新发送该授权条目。

一次更新即使成功返回，结账状态仍可能是 incomplete。如果更新运行超过 30 秒，即使部分更改已经生效，也可能返回 update_failed。两种情况下，都应先读取最新状态，再决定下一步。

4. 把最终完成权留给买家

正确的完成顺序很短，也很严格：

1. 获取最新结账状态。
2. 向买家展示当前商品、支付选择和总额。
3. 明确询问买家，是否同意按该总额提交该订单。
4. 任何内容发生变化，都要展示新状态并再次确认。
5. 只有获得同意后，才能调用 complete_checkout。
6. 只把 status: completed 当作购买成功的证据。

WBA 证明的是哪个智能体发出了请求；Shop Pay approval 授权的是一种支付机制；ready_for_complete 描述的是结账状态。这三者都不等于买家同意购买。

完成流程可能出现分支。如果配置了审核步骤，控制权会回到买家；只有买家完成审核并授权提交后，才能再次调用 complete_checkout。支付验证则不同：买家会在同一标签页中完成验证，智能体不得重复提交。应轮询 get_checkout，直到结账状态变为 completed，或再次需要智能体输入。

错误码决定了该走哪条恢复路径：

最危险的重试，是因为第一次响应不确定就再次发起完成操作。Checkout WebMCP 没有幂等键。务必先读取状态；如果状态已经是 completed，立即停止。

七个使用场景：按实际价值排序

当智能体本来就运行在买家的浏览器中时，这些场景最有价值。它们并不是在服务器上隐形运行的商家端自动化。

第一个场景最有价值。回头客已经拥有保存状态，而 WebMCP 可以减少重复输入，同时不把“更方便”伪装成“已同意”。

商业账到底怎么算

Shopify 不要求商家为这些结账工具增加新配置，但围绕它构建的购物智能体并不会因此免费。团队仍需承担模型、浏览器分发、WBA 运维、测试、隐私控制和支持成本。

目前，商家安装的 AI 购物助手价格跨度很大。Shopify App Store 官方页面中，Easy AI Shopping Assistant 的月付方案为 $9.99，Carti 的方案为 $49 至 $249，iAdvize 的月付方案则为 $290 至 $1,330。这些产品往往组合了店面聊天、推荐、分析或客服功能，因此不能直接替代买家侧的 WebMCP 智能体。

预算层面的变化其实更窄，也更实用：浏览器智能体团队可以减少维护各商店专属结账选择器的投入，把更多精力放在状态完整性、用户同意和异常处理上。若要了解更完整的平台背景，可阅读 Shopify 评测，其中分析了商家侧产品与运营取舍。

两个值得做的产品

1. Checkout WebMCP QA 与用户同意测试平台

这是最值得投入的机会。Shopify 服务商和购物智能体团队必须先确认结账是否符合条件、智能体行为是否安全，才可能放心让它接触订单。

与这个任务最接近且有数据的搜索词是 shopify checkout customization：在美国每月有 170 次搜索，同比增幅为 89%，CPC 为 $10.92。这个词覆盖的范围比 WebMCP 测试更广，但足以说明市场对结账行为和实施方式存在实际需求。

最小可售版本可以是一套 Chromium runner：打开测试结账页，按 origin 和 window 记录工具，验证 JSON 字符串参数，检测 toolchange，测试基于最新状态的更新，模拟导航返回 null 和文档列出的错误码，最后生成经过脱敏的用户同意报告。真实支付的完成操作必须保留在手动测试模式之后。

难点在于覆盖范围。工具是否可用取决于结账类型和浏览器支持，Chrome 的参数格式还在变化，而 fixture 也无法证明真实支付交接成功。产品真正的竞争力，是把这些边界清楚呈现出来，而不是声称可以普遍自动化。

2. 买家侧 Shopify AI 购物助手

浏览器扩展可以把购物者从商品搜索带到各类 Shopify 商店中符合条件的结账页，并提供可复用的确认界面，以及针对已保存支付状态的严格规则。

shopify ai shopping assistant 在美国每月有 30 次搜索，带有商业意图，CPC 为 $19.43。商家侧竞品的月付价格从 $9.99 到 $1,330，说明市场已经愿意为导购软件付费，尽管这里设想的产品位于买家侧。

MVP 需要店面搜索和购物车工具、结账工具发现、WBA、读取—更新—再读取循环、由买家控制的订单摘要，以及支付验证交接。第一阶段只做单店订单和已保存的 Shop Pay 路径。

难点在于分发。商家无需开启 Checkout WebMCP，但买家仍然需要兼容的浏览器智能体。B2B、嵌入式、移动端 SDK、跨商店，以及未使用 Shop Pay 的普通三页式结账，依旧不在支持范围内。

能力边界，就是产品边界

Checkout WebMCP 是面向符合条件的浏览器结账流程、更安全的一层接口，不是通用购买 API。

它无法在结账过程中增删商品项，无法收集新银行卡号、取消结账、操作应用定义的扩展 UI，也不能强迫被排除的结账页注册工具。它不会消除 Shop Pay 登录、3D Secure、审核步骤或其他买家操作，也不会让来自商家的文本自动变成模型可以信任的指令。

可靠的设计原则很简单：工具还在注册状态时就使用工具，以最新状态作为唯一事实来源；只要契约要求买家操作，就把页面交还给买家。

周一就做这一步

周一先给智能体增加一个统一的结账封装，不要把调用散落在整个代码库。把序列化、工具匹配、toolchange、导航返回 null、错误分类和最新状态读取都收进这一层。先跑完八项本地 fixture 用例，再在自己可控且符合条件的测试结账页上枚举 document.modelContext.getTools()。用最新状态构建并执行一次更新。只有明确确认后，才能完成受支持的测试订单；如果没有自己可以安全操作的测试订单，就停在 ready_for_complete，并将“完成结账”标记为有来源验证，而不是已经亲自测试。

如果你希望为业务打造一套把用户同意放在首位的商业智能体，可以了解 AI 智能体开发服务。