shopify-products

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Products

Shopify 产品操作

Create, update, and bulk-import Shopify products. Produces live products in the store via the GraphQL Admin API or CSV import.

创建、更新和批量导入Shopify产品。通过GraphQL Admin API或CSV导入的方式在店铺中生成可用产品。

Prerequisites

前置条件

Admin API access token (use the shopify-setup skill if not configured)
Store URL and API version from
```
shopify.config.json
```
or
```
.dev.vars
```

Admin API访问令牌（若未配置，可使用shopify-setup技能）
从
```
shopify.config.json
```
或
```
.dev.vars
```
中获取店铺URL和API版本

Workflow

工作流程

Step 1: Gather Product Data

步骤1：收集产品数据

Determine what the user wants to create or update:

Product basics: title, description (HTML), product type, vendor, tags
Variants: options (size, colour, material), prices, SKUs, inventory quantities
Images: URLs to upload, or local files
SEO: page title, meta description, URL handle
Organisation: collections, product type, tags

Accept data from:

Direct conversation (user describes products)
Spreadsheet/CSV file (user provides a file)
Website scraping (user provides a URL to extract from)

确定用户需要创建或更新的产品信息：

产品基础信息：标题、描述（HTML格式）、产品类型、供应商、标签
产品变体：选项（尺寸、颜色、材质）、价格、SKU、库存数量
产品图片：待上传的URL或本地文件
SEO设置：页面标题、元描述、URL别名
产品归类：分类、产品类型、标签

支持从以下渠道获取数据：

直接对话（用户描述产品）
电子表格/CSV文件（用户提供文件）
网站爬取（用户提供待提取数据的URL）

Step 2: Choose Method

步骤2：选择操作方法

Scenario	Method
1-5 products	GraphQL mutations
6-20 products	GraphQL with batching
20+ products	CSV import via admin
Updates to existing	GraphQL mutations
Inventory adjustments	`inventorySetQuantities` mutation

场景	方法
1-5个产品	GraphQL mutations
6-20个产品	带批量处理的GraphQL
20个以上产品	通过后台导入CSV
更新现有产品	GraphQL mutations
库存调整	`inventorySetQuantities` mutation

Step 3a: Create via GraphQL (Recommended)

步骤3a：通过GraphQL创建（推荐方式）

Single product with variants:

bash

curl -s https://{store}/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{
    "query": "mutation productCreate($product: ProductCreateInput!) { productCreate(product: $product) { product { id title } userErrors { field message } } }",
    "variables": {
      "product": {
        "title": "Example T-Shirt",
        "descriptionHtml": "<p>Premium cotton tee</p>",
        "vendor": "My Brand",
        "productType": "T-Shirts",
        "tags": ["summer", "cotton"],
        "options": ["Size", "Colour"],
        "variants": [
          {"optionValues": [{"optionName": "Size", "name": "S"}, {"optionName": "Colour", "name": "Black"}], "price": "29.95"},
          {"optionValues": [{"optionName": "Size", "name": "M"}, {"optionName": "Colour", "name": "Black"}], "price": "29.95"},
          {"optionValues": [{"optionName": "Size", "name": "L"}, {"optionName": "Colour", "name": "Black"}], "price": "29.95"}
        ]
      }
    }
  }'

See

references/graphql-mutations.md

for all mutation patterns.

Batching multiple products: Create products sequentially with a short delay between each to respect rate limits (1,000 cost points/second).

带变体的单个产品：

bash

curl -s https://{store}/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{
    "query": "mutation productCreate($product: ProductCreateInput!) { productCreate(product: $product) { product { id title } userErrors { field message } } }",
    "variables": {
      "product": {
        "title": "Example T-Shirt",
        "descriptionHtml": "<p>Premium cotton tee</p>",
        "vendor": "My Brand",
        "productType": "T-Shirts",
        "tags": ["summer", "cotton"],
        "options": ["Size", "Colour"],
        "variants": [
          {"optionValues": [{"optionName": "Size", "name": "S"}, {"optionName": "Colour", "name": "Black"}], "price": "29.95"},
          {"optionValues": [{"optionName": "Size", "name": "M"}, {"optionName": "Colour", "name": "Black"}], "price": "29.95"},
          {"optionValues": [{"optionName": "Size", "name": "L"}, {"optionName": "Colour", "name": "Black"}], "price": "29.95"}
        ]
      }
    }
  }'

所有mutation模式请查看

references/graphql-mutations.md

。

批量创建多个产品：按顺序创建产品，每个产品之间设置短暂延迟，以遵守速率限制（1000成本点/秒）。

Step 3b: Bulk Import via CSV

步骤3b：通过CSV批量导入

For 20+ products, generate a CSV and import through Shopify admin:

Generate CSV using the format in
```
references/csv-format.md
```
Use the template from
```
assets/product-csv-template.csv
```

Navigate to

https://{store}.myshopify.com/admin/products/import

Upload the CSV file
Review the preview and confirm import

Use browser automation to assist with the upload if needed.

对于20个以上产品，生成CSV文件并通过Shopify后台导入：

按照
```
references/csv-format.md
```
中的格式生成CSV文件
使用
```
assets/product-csv-template.csv
```
中的模板

访问

https://{store}.myshopify.com/admin/products/import

上传CSV文件
预览内容并确认导入

如有需要，可使用浏览器自动化工具辅助完成上传。

Step 4: Upload Product Images

步骤4：上传产品图片

Images require a two-step process — staged upload then attach:

graphql

mutation {
  stagedUploadsCreate(input: [{
    filename: "product-image.jpg"
    mimeType: "image/jpeg"
    httpMethod: POST
    resource: IMAGE
  }]) {
    stagedTargets {
      url
      resourceUrl
      parameters { name value }
    }
  }
}

Then upload to the staged URL, and attach with

productCreateMedia

Shortcut: If images are already hosted at a public URL, pass

src

directly in the product creation:

json

{
  "images": [
    { "src": "https://example.com/image.jpg", "alt": "Product front view" }
  ]
}

图片上传需要两步流程——先预上传再关联：

graphql

mutation {
  stagedUploadsCreate(input: [{
    filename: "product-image.jpg"
    mimeType: "image/jpeg"
    httpMethod: POST
    resource: IMAGE
  }]) {
    stagedTargets {
      url
      resourceUrl
      parameters { name value }
    }
  }
}

然后上传至预上传URL，并通过

productCreateMedia

关联到产品。

快捷方式：如果图片已托管在公共URL上，可在创建产品时直接传入

src

参数：

json

{
  "images": [
    { "src": "https://example.com/image.jpg", "alt": "Product front view" }
  ]
}

Step 5: Assign to Collections

步骤5：分配产品到分类

After creation, add products to collections:

graphql

mutation {
  collectionAddProducts(
    id: "gid://shopify/Collection/123456"
    productIds: ["gid://shopify/Product/789"]
  ) {
    collection { title productsCount }
    userErrors { field message }
  }
}

To find collection IDs:

graphql

{
  collections(first: 50) {
    edges {
      node { id title handle }
    }
  }
}

产品创建完成后，将其添加到分类中：

graphql

mutation {
  collectionAddProducts(
    id: "gid://shopify/Collection/123456"
    productIds: ["gid://shopify/Product/789"]
  ) {
    collection { title productsCount }
    userErrors { field message }
  }
}

获取分类ID的查询语句：

graphql

{
  collections(first: 50) {
    edges {
      node { id title handle }
    }
  }
}

Step 6: Verify

步骤6：验证结果

Query back the created products to confirm:

graphql

{
  products(first: 10, reverse: true) {
    edges {
      node {
        id title status
        variants(first: 5) { edges { node { title price inventoryQuantity } } }
        images(first: 3) { edges { node { url altText } } }
      }
    }
  }
}

Provide the admin URL for the user to review:

https://{store}.myshopify.com/admin/products

查询已创建的产品以确认操作成功：

graphql

{
  products(first: 10, reverse: true) {
    edges {
      node {
        id title status
        variants(first: 5) { edges { node { title price inventoryQuantity } } }
        images(first: 3) { edges { node { url altText } } }
      }
    }
  }
}

提供后台URL供用户查看：

https://{store}.myshopify.com/admin/products

Critical Patterns

关键注意事项

Product Status

产品状态

New products default to

DRAFT

. To make them visible:

json

{ "status": "ACTIVE" }

Always confirm with the user before setting status to

ACTIVE

新产品默认状态为

DRAFT

（草稿）。若要使其可见，需设置：

json

{ "status": "ACTIVE" }

在将状态设置为

ACTIVE

（已发布）前，请务必与用户确认。

Variant Limits

变体限制

Shopify allows max 100 variants per product and 3 options (e.g. Size, Colour, Material). If you need more, split into separate products.

Shopify允许每个产品最多包含100个变体和3个选项（如尺寸、颜色、材质）。若需要更多选项，请将产品拆分为多个独立产品。

Inventory Tracking

库存跟踪

To set inventory quantities, use

inventorySetQuantities

after product creation:

graphql

mutation {
  inventorySetQuantities(input: {
    reason: "correction"
    name: "available"
    quantities: [{
      inventoryItemId: "gid://shopify/InventoryItem/123"
      locationId: "gid://shopify/Location/456"
      quantity: 50
    }]
  }) {
    inventoryAdjustmentGroup { reason }
    userErrors { field message }
  }
}

若要设置库存数量，请在产品创建完成后使用

inventorySetQuantities

：

graphql

mutation {
  inventorySetQuantities(input: {
    reason: "correction"
    name: "available"
    quantities: [{
      inventoryItemId: "gid://shopify/InventoryItem/123"
      locationId: "gid://shopify/Location/456"
      quantity: 50
    }]
  }) {
    inventoryAdjustmentGroup { reason }
    userErrors { field message }
  }
}

Price Formatting

价格格式

Prices are strings, not numbers. Always quote them:

"price": "29.95"

not

"price": 29.95

价格需以字符串形式传入，而非数字。请务必添加引号：

"price": "29.95"

，而非

"price": 29.95

。

HTML Descriptions

HTML格式描述

Product descriptions accept HTML. Keep it simple — Shopify's editor handles basic tags:

```
<p>
```
,
```
<strong>
```
,
```
<em>
```
,
```
<ul>
```
,
```
<ol>
```
,
```
<li>
```
,
```
<h2>
```
-
```
<h6>
```
```
<a href="...">
```
for links
```
<img>
```
is stripped — use product images instead

产品描述支持HTML格式。请保持代码简洁——Shopify编辑器支持以下基础标签：

```
<p>
```
、
```
<strong>
```
、
```
<em>
```
、
```
<ul>
```
、
```
<ol>
```
、
```
<li>
```
、
```
<h2>
```
至
```
<h6>
```
```
<a href="...">
```
用于添加链接
```
<img>
```
标签会被过滤，请改用产品图片上传功能

Bulk Operations for Large Imports

大批量导入的批量操作

For 50+ products via API, use Shopify's bulk operation:

graphql

mutation {
  bulkOperationRunMutation(
    mutation: "mutation ($input: ProductInput!) { productCreate(input: $input) { product { id } userErrors { message } } }"
    stagedUploadPath: "tmp/bulk-products.jsonl"
  ) {
    bulkOperation { id status }
    userErrors { message }
  }
}

This accepts a JSONL file with one product per line, processed asynchronously.

若通过API导入50个以上产品，请使用Shopify的批量操作：

graphql

mutation {
  bulkOperationRunMutation(
    mutation: "mutation ($input: ProductInput!) { productCreate(input: $input) { product { id } userErrors { message } } }"
    stagedUploadPath: "tmp/bulk-products.jsonl"
  ) {
    bulkOperation { id status }
    userErrors { message }
  }
}

该操作接受每行一个产品的JSONL文件，并以异步方式处理。

Asset Files

资源文件

```
assets/product-csv-template.csv
```
— Blank CSV template with Shopify import headers

```
assets/product-csv-template.csv
```
— 带有Shopify导入表头的空白CSV模板

Reference Files

参考文件

```
references/graphql-mutations.md
```
— Key GraphQL mutations for product CRUD
```
references/csv-format.md
```
— Shopify CSV import column format and examples

```
references/graphql-mutations.md
```
— 产品CRUD操作的核心GraphQL mutations
```
references/csv-format.md
```
— Shopify CSV导入的列格式及示例