Shopify Storefront API：添加元字段至订单失败问题咨询

我尝试使用Storefront API中的cartMetafieldsSet查询，将用户生成的信息添加至购物车，查询返回成功，但完成结账付款后，订单上的元字段为空。现有两个问题：

1. 为何元字段未显示在订单上？
2. Storefront API的cartMetafieldsSet与Admin API的metafieldsSet有何区别？

我的GraphQL查询与变量 #

查询语句：

mutation cartMetafieldsSet($metafields: [CartMetafieldsSetInput!]!) {
  cartMetafieldsSet(metafields: $metafields) {
    metafields {
      createdAt
      description
      value
    }
  }
}

变量：

{
  "metafields": [
    {
      "key": "custom.test",
      "ownerId": "CART_ID",
      "type": "multi_line_text_field",
      "value": "This is a test value"
    }
  ]
}

后台元字段定义 #

问题1：元字段未同步至订单的原因 #

• 元字段归属对象不匹配：从截图可见，你定义的元字段归属为Order类型，但cartMetafieldsSet是给Cart对象添加元字段。Shopify不会自动将购物车元字段同步到订单，除非元字段归属同时包含Cart和Order，且配置了同步规则。
• 缺少结账后同步逻辑：Storefront API的购物车元字段默认不会自动流转到订单。你需要在订单创建后，通过Admin API或监听订单创建Webhook，将购物车的元字段复制到对应订单中。
• 元字段配置不一致：确认查询中使用的custom.test（命名空间custom、keytest）与后台定义完全一致，且字段类型（multi_line_text_field）匹配。

问题2：两个API操作的核心区别 #

• 操作对象范围：
  • cartMetafieldsSet仅能操作**购物车（Cart）**对象的元字段，是Storefront API专属接口，面向前端用户购物流程场景。
  • metafieldsSet是Admin API的通用接口，可给Shopify全类型对象（订单、产品、客户、购物车等）添加元字段，面向后台管理或服务端自动化场景。
• 权限与使用场景：
  • cartMetafieldsSet可由前端直接调用，无需Admin级权限，适合收集用户自定义购物信息，但受限于购物车生命周期。
  • metafieldsSet需要店铺管理员权限，支持批量操作、数据同步、订单后处理等场景，操作范围更广。
• 数据流转规则：
  • cartMetafieldsSet设置的购物车元字段不会自动同步到后续订单，需额外逻辑迁移。
  • Admin API设置的订单元字段直接归属订单，可直接在订单中查看，无自动流转问题。

内容的提问来源于stack exchange，提问作者Ben Seward