GraphQL Admin API 2027-01 及更高版本现在支持 orderCreate 行项目上的 variantIdentifier 字段,此前该字段仅在 unstable 版本中可用。你可以使用它通过 ID 或自定义 ID(例如存储在 metafield 中的来自其他系统的 listing ID)来识别产品变体。这是对 2027-01 候选版本的增量更新,因此无需采取任何操作。
变更内容
在 2027-01 版本中,OrderCreateLineItemInput 包含 variantIdentifier 字段。请提供以下其中一项:
- id:产品变体的全局 ID。
- customId:id 变体上 namespace、key 和 value 的元数据定义。如果省略 namespace,则使用你的应用保留的命名空间。
请使用 variantIdentifier 代替 variantId 和 productId。如果行项目将 variantIdentifier 与这些字段之一一起设置,则 orderCreate 将返回带有 INVALID 代码的用户错误。
要通过自定义 ID 查找变体,商店需要为产品变体创建类型为 id 的 metafield 定义,且你的应用必须能够读取它。如果该定义不存在,则 orderCreate 会返回一个 INVALID 用户错误,提示需要该定义。
如果商店中没有变体匹配某个标识符,则 orderCreate 将为该行项目返回带有 VARIANT_IDENTIFIER_NOT_FOUND 代码的用户错误,并且不会创建订单。使用 variantId 的行项目仍按原方式工作。
受影响范围
此更改适用于使用 orderCreate 创建订单的应用。对于通过外部系统 ID 识别产品的销售渠道和集成来说,这非常有用。
- API 版本 2027-01 及更高版本包括 variantIdentifier。
- API 版本 2026-10 及更早版本不包含此字段。
- 已经在 unstable 上使用 variantIdentifier 的应用可以迁移到 2027-01 而无需更改其请求。
variantIdentifier 不需要超出 orderCreate 已要求的访问范围。自定义 ID 查找仅能找到你的应用可以读取的 metafields。
应对措施
无需采取任何操作。如需开始在订单行项目上使用自定义 ID:
- 检查商店是否为产品变体创建了类型为 id 的 metafield 定义,并且每个变体是否在该 metafield 中存储了其外部 ID。
- 将您的应用更新到 API 版本 2027-01。
- 在你通过自定义 ID 标识的每个行项目上传递 variantIdentifier:
此示例为 custom.listing_id metafield 为 LST-10045 的变体创建订单。替换为你的 metafield 定义和外部 ID 的命名空间、键和值,并添加你的应用通常发送的其他订单字段。
- 在开发商店中进行测试。创建一个具有已知自定义 ID 的订单,并检查行项目是否指向预期的变体。然后发送一个未知值,并检查 userErrors 是否返回 VARIANT_IDENTIFIER_NOT_FOUND。
影响说明
在此之前,只知道变体外部 ID 的应用有两个选择:它可以维护从外部 ID 到 Shopify 变体 ID 的自己的映射,或者在调用 orderCreate 之前使用 productVariantByIdentifier 查找每个变体。现在,你可以在创建订单的同一请求中传递外部 ID。
相关文档
- 使用自定义 ID
- orderCreate 变异
- OrderCreateLineItemInput 订单创建行项目输入参考

