Shopify Storefront GraphQL API — 2026-04

Self-contained reference for the Storefront GraphQL API, version 2026-04. Use this skill whenever you need to write, audit, or explain Storefront GraphQL for a headless / custom storefront. Detailed field cheat sheets live in references/.

> 中文说明（针对国内开发者）：本 skill 提供可直接复制的 GraphQL 模板，关键概念附中文注解。国内访问 Shopify 海外节点可能有延迟/超时，推荐用服务端中转或 Cloudflare Worker 代理（见 §8）。如需人民币展示与中文文案，用 @inContext(country: CN, language: ZH)（见 §2、§8）。

When to use / 适用场景

• Fetching products, collections, search results, blogs/articles/pages, menus, or localization data.
• Building or managing a Cart (create → add lines → update → remove → checkout URL).
• Customer account flows (login token, register, address management, password recovery) — legacy customer accounts (Customer Account API v1).
• Internationalization via @inContext (country / language / buyer / visitorConsent).
• Advanced: reading Metafields / Metaobjects (custom fields) and writing cart-level metafields.
• Any GraphQL that hits https://{shop}.myshopify.com/api/2026-04/graphql.json.

Do NOT use for / 不适用

• Admin operations (products create/update, orders, inventory, metafields write) → use shopify-admin.
• Customer Account API v2 / new accounts (token exchange via shopify.customer-account / Customer Account API) — that is a separate OAuth flow, not covered here in detail.

1. Endpoint, versioning, auth / 端点、版本与认证

Endpoint (POST only — there is no REST Storefront API)

POST https://{shop}.myshopify.com/api/2026-04/graphql.json
Content-Type: application/json

Body: { "query": "...", "variables": { ... } }.

Versioning / 版本

• Storefront API ships a new version every quarter. Pin the version in the URL (e.g. 2026-04).
• Other valid versions around this era: unstable, 2026-10, 2026-07, 2026-04, 2026-01, 2025-10. Always pin a stable version in production.
• 新版本每季度发布一次；生产环境务必固定稳定版本，避免 unstable 破坏性变更。

Authentication — two modes / 两种认证模式

Tokenless 适合公开目录与购物车浏览。需要客户登录、metafields、菜单、产品标签时必须用 Storefront access token。

Creating a Storefront access token / 创建令牌

• Via Admin GraphQL: storefrontAccessTokenCreate (input: { namespace }) → returns storefrontAccessToken { accessToken }.
• Via Admin REST: POST /admin/api/{version}/storefront_access_tokens.json with { "storefront_access_token": { "name": "My App" } }.
• Public token = used from browser / mobile; Private token = used server-side / Hydrogen backend. Never expose a private token in client code.（私有 token 绝不能出现在前端代码）

cURL template

curl -X POST https://{shop}.myshopify.com/api/2026-04/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Storefront-Access-Token: {storefront_access_token}' \
  -d '{"query":"...","variables":{...}}'

> Money caveat（金额坑）: Storefront GraphQL returns prices as MoneyV2 { amount: "19.99", currencyCode: "USD" } — a decimal string in major units, NOT cents. (This differs from Liquid {{ variant.price }} / storefront .js JSON which return integer cents. Do not apply the ×100 / ÷100 normalization here.)
> 中文：金额是「元」为单位的字符串（如 "19.99"），不是「分」整数。切勿做 ×100/÷100 换算。

2. Directives / 指令

@inContext — set request context / 设置请求上下文

Place on query or mutation. Key args:
- country (e.g. US, FR, CN) — international pricing / presentment currency（多币种展示价）.
- language (e.g. EN, FR, ZH) — localized content (2022-04+).
- buyer (2024-04+) — B2B buyer identity / company location context.
- visitorConsent (2025-10+) — { analytics: Boolean, marketing: Boolean, saleOfData: Boolean, targeting: Boolean }; encoded into checkoutUrl for compliance.

query ($country: CountryCode, $language: LanguageCode)
  @inContext(country: $country, language: $language) {
  product(handle: "guitar") { title priceRangeV2 { minVariantPrice { amount currencyCode } } }
}

> 国内场景：@inContext(country: CN, language: ZH) 可同时拿到人民币 presentment 价与中文文案。

@defer — stream partial results (developer preview in unstable)

Returns non-deferred fields immediately, deferred (@defer) fields stream after. Required for carrier-calculated cart rates (cart.deliveryGroups(withCarrierRates: true)). Generally only available in unstable.

3. Root fields at a glance / 根字段一览

Queries（查询）：

Mutations (cart) / 购物车突变：
cartCreate, cartLinesAdd, cartLinesUpdate, cartLinesRemove, cartNoteUpdate, cartBuyerIdentityUpdate, cartDiscountCodesUpdate, cartAttributesUpdate, cartGiftCardCodesAdd, cartDeliveryAddressesAdd, cartSelectedDeliveryOptionsUpdate, cartMetafieldsSet, cartMetafieldDelete.

Mutations (customer — legacy accounts) / 客户突变（legacy 账户）：
customerAccessTokenCreate, customerAccessTokenRenew, customerCreate, customerActivate, customerActivateByUrl, customerRecover, customerReset, customerResetByUrl, customerUpdate, customerAddressCreate, customerAddressDelete, customerAddressUpdate, customerDefaultAddressUpdate.

> Customer mutations require scopes such as unauthenticated_write_customers / unauthenticated_read_customer_tags. customerAccessTokenCreate is legacy-account only.
> 注意：客户突变需要相应 scope，且 customerAccessTokenCreate 仅支持 legacy 账户。

See references/queries.md and references/mutations.md for full templates and input shapes. 进阶的 Metafields / Metaobjects 查询见 references/queries.md §8。

4. Required workflow when writing Storefront GraphQL / 编写规范流程

1. Pick the right root field (use the lists above or references/). 选对根字段。
2. Select only the fields you need — customer-facing queries are billed by complexity. Never ... on ProductVariant { ... } more than necessary. 只取需要的字段，控制复杂度。
3. Always request userErrors / customerUserErrors on mutations so failures are debuggable. 突变务必选 userErrors，否则失败会静默。
4. Use pagination (first + pageInfo { hasNextPage, endCursor }, then after) for any list. 列表务必分页。
5. Never log passwords / access tokens. Transmit over HTTPS only. 切勿记录密码/token，仅走 HTTPS。
6. Wrap GraphQL in a graphql code block when returning it. 返回时用 graphql 代码块包裹。

5. Common patterns / 常见模式

Cart lifecycle / 购物车生命周期

1. cartCreate(input: { lines: [{ merchandiseId, quantity }], ... }) → store cart.id (e.g. in a cookie).
2. cartLinesAdd / cartLinesUpdate / cartLinesRemove using the stored cart.id.
3. cartBuyerIdentityUpdate (email/country) for accurate tax/shipping.
4. Read cart.checkoutUrl and redirect the buyer to Shopify web checkout to complete the purchase.

Customer login / 客户登录

customerAccessTokenCreate(input: { email, password }) → persist customerAccessToken.accessToken → pass as customer(customerAccessToken: $token) for reads, or as the customerAccessToken arg on customer mutations.

Localization / 本地化

Wrap any query with @inContext(country: $country, language: $language) to get presentment prices and translated content.

6. Reference files / 参考文件

• references/auth-versioning.md — endpoint, auth modes, scopes, version table, @inContext/@defer details.（端点、认证、scope、版本、指令）
• references/queries.md — root query list + copy-paste query templates (products, product, collections, cart, customer, search, localization, metafields / metaobjects).
• references/mutations.md — cart + customer mutation templates with exact input object shapes (CartInput, CartLineInput, CustomerCreateInput, MailingAddressInput, cartMetafieldsSet …).
• references/objects.md — key object field cheat sheets: Product, ProductVariant, Cart, CartLine, Customer, Collection, Image, MoneyV2, PageInfo, Metafield, Metaobject.
• references/error-handling.md — NEW 错误处理：双错误通道、HTTP 状态码、成本预算/节流、常见错误码、退避重试、CORS 与国内网络方案，以及 cartCreate/登录的成功与失败配对示例。

7. Official docs / 官方文档

• API home: https://shopify.dev/docs/api/storefront/2026-04
• Cart guide: https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage
• Customer accounts (legacy): https://shopify.dev/docs/api/storefront/2026-04/mutations/customerAccessTokenCreate
• Versioning: https://shopify.dev/docs/api/usage/versioning

8. 中文快速上手与国内使用场景（Domestic / CN developers）

8.1 三分钟上手（中文）

1. 确定要不要 token：公开商品/购物车浏览用 tokenless（不加 header）；要登录、菜单、metafields 用 Storefront access token。
2. 复制 references/queries.md 或 references/mutations.md 里的模板，替换 {shop} 与变量。
3. 金额按 MoneyV2.amount 字符串（元）处理，不要当分。
4. 列表查询加 pageInfo 分页。
5. mutation 一定选 userErrors。

8.2 国内网络访问（延迟 / 超时 / 合规）

• Shopify 节点在海外，国内直连可能高延迟、偶发超时。生产建议 服务端中转 或 Cloudflare Worker 代理：后端持有 token 转发，前端只与同源后端通信，并可缓存只读查询。
• Worker 反代模式（仅作示意，不要覆盖你现有的 Admin/Metafield Worker）：
  js export default { async fetch(request, env) { const url = new URL(request.url); if (url.pathname.startsWith('/api/storefront')) { const shopResp = await fetch( `https://${env.SHOP}/api/2026-04/graphql.json`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Shopify-Storefront-Access-Token': env.STOREFRONT_TOKEN, }, body: await request.text(), } ); return new Response(shopResp.body, { headers: { 'content-type': 'application/json', 'cache-control': 's-maxage=60' }, }); } return new Response('Not found', { status: 404 }); }, };
• CORS：Storefront 端点支持浏览器跨域直连（tokenless 或 public token）。私有 token 绝不能进前端。
• 前端直连应设超时（如 10s）并配合 references/error-handling.md §5 的退避重试。

8.3 货币与本地化（CNY / 中文）

• 人民币展示：@inContext(country: CN) 取 presentment 价（仍按 MoneyV2「元」字符串返回）。
• 中文文案：@inContext(language: ZH)。
• 多币种切换：读取 localization.availableCountries 让用户选国家/币种。

9. 常见陷阱（Common Pitfalls）— 评测建议补充

1. 金额单位搞错：Storefront GraphQL 金额是「元」字符串；Liquid / .js JSON 是「分」整数。两者不要混用 ×100/÷100。
2. 复杂度超限：tokenless 单查询上限 1000，过度嵌套/拉全字段会 MAX_COMPLEXITY_EXCEEDED。控制字段、用分页。
3. 购物车失效：cartId 长期不活动会过期 → CART_NOT_FOUND / INVALID_CART。客户端应存 cart.id 并在失效时重建。
4. tokenless 够不着的数据：metafields、菜单、客户、产品标签必须带 Storefront access token，否则字段为空或报错。
5. 私有 token 泄露：private token 只能服务端用；前端只用 public token 或走中转。
6. 客户 API 仅 legacy：customerAccessTokenCreate 等是 legacy 账户；新 Customer Account API v2 是另一套 OAuth，本 skill 不覆盖。
7. 漏选 userErrors：mutation 不设 userErrors 会让业务失败静默，难以排查。
8. 把 userErrors 当异常重试：userErrors 是正常响应（HTTP 200），重试只会重复同样的业务错误；只有 errors[]（THROTTLED / 5xx / 网络）才退避重试（见 error-handling.md §5）。
9. 分页没接 pageInfo：列表不翻页会丢数据；用 endCursor + after 循环。
10. productByHandle 已废弃：用 product(handle: $handle)。
11. @inContext 的 country 与 presentment 币种：未设 country 时返回店铺默认币种，切换币种必须带 country。

10. 进阶：自定义字段（Metafields / Metaobjects）

Storefront 读取自定义字段需 Storefront access token：
- 单字段：metafield(namespace: "custom", key: "spec") { value type }
- 批量：metafields(identifiers: [{namespace, key}]) { ... }
- 自定义对象：metaobject(handle: "author") { ... } / metaobjects(type: "author", first: 10) { ... }
- 购物车级自定义字段（写）：cartMetafieldsSet / cartMetafieldDelete（见 references/mutations.md）。
完整模板与字段见 references/queries.md §8 与 references/objects.md（Metafield / Metaobject 速查）。

11. 场景速查：我想做 X → 用哪个 API（触发方式）

> 评测指出「缺少在什么场景用什么功能的说明」。下表直接把需求映射到根字段/突变（A·触发方式 4.5→4.8）。

12. 限制与边界汇总（能力边界，集中说明）

> 评测指出「限制信息分散」。以下集中列出所有硬性边界（A·能力边界 4.5→4.7），与 §9 陷阱互补。

1. 认证边界：tokenless 取不到 metafields、菜单、客户、产品标签——这些必须带 Storefront access token。
2. 密钥边界：private token 仅服务端/Hydrogen 后端用，绝不能进前端；前端只用 public token 或走中转。
3. 账户边界：customerAccessTokenCreate 等客户突变仅 legacy 账户；新 Customer Account API v2 是另一套 OAuth 流程，本 skill 不覆盖。
4. 复杂度边界：tokenless 单查询复杂度上限 1,000，超限报 MAX_COMPLEXITY_EXCEEDED；控制字段、用分页。
5. 购物车生命周期：cartId 长期不活跃会过期，返回 CART_NOT_FOUND/INVALID_CART——客户端应存 cart.id 并在失效时重建。
6. 金额单位：Storefront GraphQL 金额是「元」字符串；Liquid / .js JSON 是「分」整数。勿混用 ×100/÷100。
7. 分页强制：所有列表用 first（≤250）+ pageInfo{hasNextPage,endCursor} 翻页，否则丢数据。
8. 废弃字段：productByHandle 已废弃 → 用 product(handle:)。
9. 传输方式：仅 POST .../graphql.json，无 REST 版 Storefront API。
10. 版本：每季度发版，生产固定稳定版（如 2026-04），勿用 unstable。

13. 质量评测（优化后，含详细子维度）

13.1 总览

13.2 详细子维度（据评测明细）