Admin API 写 metafield 报 invalid value 怎么办

现象#

metafieldsSet 返回 INVALID_VALUE，同一个 key 在后台手工能填。

原因#

• type 与值格式不匹配，如 number_integer 传了 "12" 带引号以外的格式
• json 类型没有做字符串化
• list.single_line_text_field 需要 JSON 数组字符串
• definition 不存在或未对当前 owner 类型开放

处理步骤#

1. 先查 metafieldDefinitions 确认该 namespace.key 的类型与 ownerType
2. 按类型构造值：整数直接放数字，json 用 json.dumps，列表用 JSON 数组字符串
3. 写入前确保 definition 已创建并 access.admin 可写
4. 读回 metafield.value 与 type 校验

验收标准#

写入成功且后台商品页能看到该字段，读回类型与值正确，无 INVALID_VALUE。