能否通过Shopify REST Admin API按元字段值筛选客户？

GraphQL 查询方案 #

Shopify GraphQL API支持通过元字段筛选客户，但必须精准匹配元字段的命名空间和键名，这是多数人踩坑的核心点。假设你的VAT Number元字段命名空间为custom、键为vat_number，查询示例如下：

query {
  customers(first: 25, query: "metafields.custom.vat_number:'DE123456789'") {
    edges {
      node {
        id
        email
        metafields(namespace: "custom", key: "vat_number") {
          key
          value
        }
      }
    }
  }
}

• 注意事项：
  • 查询字符串里的命名空间、键名必须和实际存储的完全一致，大小写敏感
  • 若元字段是无命名空间的旧格式，查询语法改为metafields.vat_number:'DE123456789'
  • 必须拥有read_customers权限范围，否则会返回权限错误

REST API 查询方案 #

REST API同样支持通过元字段过滤，需使用完整的元字段键格式：

GET /admin/api/2024-07/customers.json?query=metafields.custom.vat_number:'DE123456789'

如果是无命名空间的旧版元字段，调整为：

GET /admin/api/2024-07/customers.json?query=metafields.vat_number:'DE123456789'

常见排查点 #

• 确认元字段已正确关联到客户对象：检查客户详情页的元字段列表，确保目标字段存在且值准确
• 使用最新稳定版API：部分旧版本API对元字段过滤的支持有限，建议切换到当前最新的API版本
• 特殊字符转义：若VAT号码包含+、*这类特殊字符，需在查询字符串中做URL转义（GraphQL中用反斜杠转义）

内容的提问来源于stack exchange，提问作者Carlos Paiva