Shopify GraphQL函数相关Mutation在CURL/Postman失效，GraphiQL正常

数据老陈

2026-7-10

解决方案

1. 核对请求令牌的店铺关联性

GraphiQL在Shopify后台运行时自动绑定当前店铺上下文，而CURL/Postman如果使用应用全局令牌，会因权限范围不匹配找不到Function。

必须使用目标店铺的专属访问令牌，前往Shopify后台对应应用设置重新生成该店铺的令牌，替换CURL/Postman中的令牌值。

2. 确保Function ID完全正确

Shopify的Function ID是带前缀的全局ID（例如gid://shopify/Function/xxx），且区分大小写，手动复制时容易遗漏前缀或打错字符：

直接从GraphiQL的成功请求里复制完整的Function ID，不要手动输入或修改格式。

3. 补全请求头的关键信息

GraphiQL会自动填充必要请求头，CURL/Postman常因遗漏导致上下文错误：

必须添加X-Shopify-Access-Token头，值为目标店铺的访问令牌；
将Content-Type设置为application/json；
Accept头指定正确API版本，例如Accept: application/json; Shopify-Api-Version=2024-04（与GraphiQL使用的版本保持一致）。

4. 确认Function已部署到目标店铺

如果是用Shopify CLI创建的Function，仅在GraphiQL可见不代表已完成部署：

执行shopify function deploy命令，确保终端显示部署成功，且绑定的是目标店铺。

5. 检查请求体的JSON格式

手动编写请求体易出现引号未转义、逗号缺失等错误，导致Shopify解析失败并误报Function不存在：

直接将GraphiQL里的完整请求体复制到CURL/Postman，不要手动调整结构。示例正确请求体：

{
  "query": "mutation discountAutomaticAppCreate($input: DiscountAutomaticAppInput!) { discountAutomaticAppCreate(input: $input) { discountAutomatic { id } userErrors { field message } } }",
  "variables": {
    "input": {
      "title": "Test Auto Discount",
      "functionId": "gid://shopify/Function/123456789",
      "startsAt": "2024-01-01T00:00:00Z"
    }
  }
}