Back to Details

shopify-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify Setup

Shopify 环境设置

Set up working Shopify CLI authentication and Admin API access for a store. Produces a verified API connection ready for product and content management.
为Shopify店铺配置可用的Shopify CLI身份验证与Admin API访问权限，创建可用于产品及内容管理的已验证API连接。

Workflow

操作流程

Step 1: Check Prerequisites

步骤1：检查前置条件

Verify the Shopify CLI is installed:
bash
shopify version
If not installed:
bash
npm install -g @shopify/cli
确认Shopify CLI已安装：
bash
shopify version
若未安装：
bash
npm install -g @shopify/cli

Step 2: Authenticate with the Store

步骤2：与店铺进行身份验证

bash
shopify auth login --store mystore.myshopify.com
This opens a browser for OAuth. The user must be a store owner or staff member with appropriate permissions.
After login, verify:
bash
shopify store info
bash
shopify auth login --store mystore.myshopify.com
此命令会打开浏览器进行OAuth验证，用户需为店铺所有者或拥有相应权限的工作人员。
登录完成后，验证连接：
bash
shopify store info

Step 3: Create a Custom App for API Access

步骤3：创建用于API访问的自定义应用

Custom apps provide stable Admin API access tokens (unlike CLI session tokens which expire).
Check if an app already exists: Ask the user if they have a custom app set up. If yes, skip to Step 4.
If no custom app exists, guide the user through creation via browser:
  1. Navigate to 
    https://{store}.myshopify.com/admin/settings/apps/development
  2. Click Create an app
  3. Name it (e.g. "Claude Code Integration")
  4. Click Configure Admin API scopes
  5. Enable these scopes (see 
    references/api-scopes.md
    for details): 
    • read_products
      , 
      write_products
    • read_content
      , 
      write_content
    • read_product_listings
    • read_inventory
      , 
      write_inventory
    • read_files
      , 
      write_files
  6. Click Save then Install app
  7. Copy the Admin API access token (shown only once)
Use browser automation (Chrome MCP or playwright-cli) if the user prefers assistance navigating the admin.
自定义应用可提供稳定的Admin API访问令牌（与会过期的CLI会话令牌不同）。
检查是否已存在应用：询问用户是否已配置自定义应用，若是则跳过至步骤4。
若未创建自定义应用，引导用户通过浏览器操作：
  1. 访问 
    https://{store}.myshopify.com/admin/settings/apps/development
  2. 点击创建应用
  3. 为应用命名（例如"Claude Code Integration"）
  4. 点击配置Admin API权限范围
  5. 启用以下权限范围（详情请查看
    references/api-scopes.md
    ）： 
    • read_products
      , 
      write_products
    • read_content
      , 
      write_content
    • read_product_listings
    • read_inventory
      , 
      write_inventory
    • read_files
      , 
      write_files
  6. 点击保存，然后点击安装应用
  7. 复制Admin API访问令牌（仅显示一次）
若用户需要协助操作后台，可使用浏览器自动化工具（Chrome MCP或playwright-cli）。

Step 4: Store the Access Token

步骤4：存储访问令牌

Store the token securely. Never commit it to git.
For project use — create 
.dev.vars
:
SHOPIFY_STORE=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
Ensure 
.dev.vars
is in 
.gitignore
.
For cross-project use — store in Vault:
Use mcp__vault__secret_set with:
  name: "shopify-{store-name}-token"
  value: the access token
  tags: ["shopify", "api"]
安全存储令牌，切勿将其提交至git仓库。
项目内使用 — 创建
.dev.vars
文件：
SHOPIFY_STORE=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
确保
.dev.vars
已添加至
.gitignore
文件中。
跨项目使用 — 存储至Vault：
Use mcp__vault__secret_set with:
  name: "shopify-{store-name}-token"
  value: the access token
  tags: ["shopify", "api"]

Step 5: Verify API Access

步骤5：验证API访问权限

Test the connection with a simple GraphQL query:
bash
curl -s https://{store}.myshopify.com/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "{ shop { name primaryDomain { url } } }"}' | jq .
Expected response includes the shop name and domain. If you get a 401, the token is invalid or expired — recreate the app.
使用简单的GraphQL查询测试连接：
bash
curl -s https://{store}.myshopify.com/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "{ shop { name primaryDomain { url } } }"}' | jq .
预期响应应包含店铺名称及域名。若返回401错误，说明令牌无效或已过期，请重新创建应用。

Step 6: Save Store Config

步骤6：保存店铺配置

Create a 
shopify.config.json
in the project root for other skills to reference:
json
{
  "store": "mystore.myshopify.com",
  "apiVersion": "2025-01",
  "tokenSource": ".dev.vars"
}
在项目根目录创建
shopify.config.json
文件，供其他技能调用：
json
{
  "store": "mystore.myshopify.com",
  "apiVersion": "2025-01",
  "tokenSource": ".dev.vars"
}

Critical Patterns

关键注意事项

API Version

API版本

Always specify an explicit API version (e.g. 
2025-01
). Using 
unstable
in production will break without warning. Shopify retires API versions quarterly.
请始终指定明确的API版本（例如
2025-01
）。在生产环境中使用
unstable
版本会无预警地出现故障，Shopify每季度会淘汰旧版API。

Token Types

令牌类型

TokenFormatUse
Admin API access token
shpat_*
Custom apps — stable, long-lived
CLI session tokenShort-livedShopify CLI commands only
Storefront API token
shpca_*
Public storefront queries
This skill sets up Admin API access tokens — the right choice for product and content management.
令牌类型格式用途
Admin API访问令牌
shpat_*
自定义应用使用 — 稳定、长期有效
CLI会话令牌短期有效仅用于Shopify CLI命令
Storefront API令牌
shpca_*
公开店铺前台查询使用
本技能配置的是Admin API访问令牌，这是产品及内容管理的最佳选择。

Rate Limits

速率限制

Shopify uses a leaky bucket rate limiter:
  • REST: 40 requests/second burst, 2/second sustained
  • GraphQL: 1,000 cost points per second, max 2,000 points per query
For bulk operations, use the 
bulkOperationRunQuery
mutation instead of looping.
Shopify采用漏桶算法进行速率限制：
  • REST接口：突发请求上限40次/秒，持续请求上限2次/秒
  • GraphQL接口：每秒1000成本点，单查询最高2000成本点
对于批量操作，请使用
bulkOperationRunQuery
突变而非循环调用。

Reference Files

参考文件

  • references/api-scopes.md
    — Admin API scopes needed for product and content management
  • references/api-scopes.md
    — 产品及内容管理所需的Admin API权限范围