shopify-admin-collection-reorganization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

Reorders products in a manual Shopify collection by inventory level without navigating the Shopify admin UI. This skill queries all products in the collection, computes the desired sort order by

totalInventory

, and applies it in a single

collectionReorderProducts

mutation. Note: only works on manual (custom) collections — smart collections managed by Shopify rules are not supported.

无需操作Shopify管理后台UI，即可按库存水平对Shopify手动集合中的产品进行重新排序。本技能会查询集合中的所有产品，根据

totalInventory

计算预期排序，然后通过单次

collectionReorderProducts

mutation应用排序。注意：仅适用于手动（自定义）集合——不支持由Shopify规则管理的智能集合。

Prerequisites

前置要求

Authenticated Shopify CLI session:
```
shopify auth login --store <domain>
```
API scopes:
```
read_products
```
,
```
write_products
```

已认证的Shopify CLI会话：
```
shopify auth login --store <domain>
```
API权限：
```
read_products
```
、
```
write_products
```

Parameters

参数

Parameter	Type	Required	Default	Description
store	string	yes	—	Store domain (e.g., mystore.myshopify.com)
format	string	no	human	Output format: `human` or `json`
dry_run	bool	no	false	Preview operations without executing mutations
collection_id	string	yes	—	GID of the manual collection (e.g., `gid://shopify/Collection/123` )
sort_by	string	no	inventory_desc	`inventory_desc` (highest stock first) or `inventory_asc` (lowest stock first)

参数	类型	是否必填	默认值	描述
store	string	是	—	商店域名（例如：mystore.myshopify.com）
format	string	否	human	输出格式： `human` 或 `json`
dry_run	bool	否	false	预览操作但不执行mutation
collection_id	string	是	—	手动集合的GID（例如： `gid://shopify/Collection/123` ）
sort_by	string	否	inventory_desc	`inventory_desc` （库存高的在前）或 `inventory_asc` （库存低的在前）

Safety

安全提示

⚠️ Step 2 executes
collectionReorderProducts
which changes the product display order immediately. The sort is reversible — run again with the opposite
sort_by
to restore previous order — but the original custom order cannot be recovered once overwritten. The
moves
array passed to the mutation must be complete; partial moves produce undefined ordering. Always run with
dry_run: true
first to review the computed sort order before committing.

collectionReorderProducts

only works on manual (custom) collections. If the collection has

sortOrder

other than

MANUAL

, the skill must abort with a clear message: "Cannot reorder: collection sort order is not MANUAL. Switch the collection to manual sorting in the Shopify admin first."

⚠️ 步骤2执行的
collectionReorderProducts
会立即更改产品展示顺序。排序是可撤销的——使用相反的
sort_by
参数再次运行即可恢复之前的顺序，但原始自定义顺序一旦被覆盖就无法恢复。传递给mutation的
moves
数组必须完整；部分移动会导致未定义的排序。提交前请务必先使用
dry_run: true
运行，预览计算出的排序结果。

collectionReorderProducts

仅适用于手动（自定义）集合。如果集合的

sortOrder

不是

MANUAL

，本技能必须中止并返回清晰提示：“无法重新排序：集合的排序方式不是手动排序。请先在Shopify管理后台将集合切换为手动排序。”

Workflow Steps

工作流步骤

OPERATION:
```
collection
```
— query Inputs:
```
id: <collection_id>
```
,
```
first: 250
```
, pagination cursor Expected output: Collection metadata (title,
```
sortOrder
```
) and all product nodes with
```
totalInventory
```
; verify
```
sortOrder == "MANUAL"
```
— abort if not; paginate until all products fetched

OPERATION:

collectionReorderProducts

— mutation Inputs:

id: <collection_id>

moves

array sorted by

totalInventory

per

sort_by

parameter — each move is

{id: <product_id>, newPosition: "<index>"}

(0-indexed string) Expected output:

job.id

and

job.done

;

userErrors

操作：
```
collection
```
— 查询 输入：
```
id: <collection_id>
```
、
```
first: 250
```
、分页游标 预期输出： 集合元数据（标题、
```
sortOrder
```
）以及所有带
```
totalInventory
```
的产品节点；验证
```
sortOrder == "MANUAL"
```
——不满足则中止；分页直到拉取到所有产品

操作：

collectionReorderProducts

— mutation 输入：

id: <collection_id>

、根据

sort_by

参数按

totalInventory

排序的

moves

数组——每个移动项为

{id: <product_id>, newPosition: "<index>"}

（0索引的字符串） 预期输出：

job.id

和

job.done

；

userErrors

GraphQL Operations

GraphQL 操作

graphql

undefined

graphql

undefined

collection:query — validated against api_version 2025-01

query CollectionProducts($id: ID!, $first: Int!, $after: String) { collection(id: $id) { id title sortOrder products(first: $first, after: $after) { edges { node { id title totalInventory variants(first: 100) { edges { node { inventoryQuantity } } } } } pageInfo { hasNextPage endCursor } } } }


```graphql


```graphql

collectionReorderProducts:mutation — validated against api_version 2025-01

mutation CollectionReorderProducts($id: ID!, $moves: [MoveInput!]!) { collectionReorderProducts(id: $id, moves: $moves) { job { id done } userErrors { field message } } }

undefined

mutation CollectionReorderProducts($id: ID!, $moves: [MoveInput!]!) { collectionReorderProducts(id: $id, moves: $moves) { job { id done } userErrors { field message } } }

undefined

Session Tracking

会话跟踪

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: collection-reorganization            ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

dry_run: true

, prefix every mutation step with

[DRY RUN]

and do not execute it.

On completion, emit:

For

format: human

(default):

══════════════════════════════════════════════
OUTCOME SUMMARY
  Collection:          <title>
  Products reordered:  <n>
  Sort order:          <inventory_desc|inventory_asc>
  Errors:              0
  Output:              none
══════════════════════════════════════════════

For

format: json

, emit:

json

{
  "skill": "collection-reorganization",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "CollectionProducts", "type": "query", "params_summary": "collection_id: <gid>, first: 250", "result_summary": "<n> products fetched", "skipped": false },
    { "step": 2, "operation": "CollectionReorderProducts", "type": "mutation", "params_summary": "sort_by: inventory_desc, <n> moves", "result_summary": "job submitted", "skipped": false }
  ],
  "outcome": {
    "collection_title": "<title>",
    "products_reordered": 0,
    "sort_by": "inventory_desc",
    "errors": 0,
    "output_file": null
  }
}

Claude 必须在每个阶段输出以下内容，这是强制要求。

启动时，输出：

╔══════════════════════════════════════════════╗
║  SKILL: collection-reorganization            ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每步完成后，输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

如果

dry_run: true

，在每个mutation步骤前加上

[DRY RUN]

且不执行该步骤。

完成时，输出：

对于

format: human

（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Collection:          <title>
  Products reordered:  <n>
  Sort order:          <inventory_desc|inventory_asc>
  Errors:              0
  Output:              none
══════════════════════════════════════════════

对于

format: json

，输出：

json

{
  "skill": "collection-reorganization",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "CollectionProducts", "type": "query", "params_summary": "collection_id: <gid>, first: 250", "result_summary": "<n> products fetched", "skipped": false },
    { "step": 2, "operation": "CollectionReorderProducts", "type": "mutation", "params_summary": "sort_by: inventory_desc, <n> moves", "result_summary": "job submitted", "skipped": false }
  ],
  "outcome": {
    "collection_title": "<title>",
    "products_reordered": 0,
    "sort_by": "inventory_desc",
    "errors": 0,
    "output_file": null
  }
}

Output Format

输出格式

No CSV output. The skill reports the new sort order in the session completion summary. Use

dry_run: true

to preview the computed position list without committing.

不提供CSV输出。本技能会在会话完成摘要中报告新的排序顺序。使用

dry_run: true

可预览计算出的位置列表而不提交更改。

Error Handling

错误处理

Error	Cause	Recovery
`sortOrder is not MANUAL`	Collection is a smart/automated collection	Switch collection to manual ordering in Shopify admin
`userErrors` in mutation	Invalid product ID or position	Check all product IDs belong to the collection
Collection not found	Invalid collection GID	Verify the GID in Shopify admin
Rate limit (429)	Too many paginated requests	Reduce `first` to 100 and retry

错误	原因	解决方案
`sortOrder is not MANUAL`	集合是智能/自动集合	在Shopify管理后台将集合切换为手动排序
mutation中的 `userErrors`	产品ID或位置无效	检查所有产品ID是否属于该集合
集合未找到	集合GID无效	在Shopify管理后台验证GID
速率限制（429）	分页请求过多	将 `first` 参数减少到100后重试

Best Practices

最佳实践

Always run
```
dry_run: true
```
first — the skill will print the proposed product order so you can verify before committing.
```
collectionReorderProducts
```
is asynchronous —
```
job.done
```
may be
```
false
```
immediately. The sort completes within a few seconds; refresh the storefront to verify.
Use
```
sort_by: inventory_asc
```
to push out-of-stock products to the bottom of the collection page, reducing customer frustration.
For large collections (250+ products), pagination is automatic but increases execution time. Consider running during off-peak hours.
This skill only reads
```
totalInventory
```
from the products node — it does not aggregate per-location. If you need location-specific sorting, use the
```
low-inventory-restock
```
skill to identify which products to prioritize.

始终先使用
```
dry_run: true
```
运行——技能会打印拟议的产品顺序，你可以在提交前进行验证。
```
collectionReorderProducts
```
是异步的——
```
job.done
```
可能会立即返回
```
false
```
。排序会在数秒内完成；刷新店铺前端即可验证。
使用
```
sort_by: inventory_asc
```
可将无货产品推送到集合页面底部，减少客户不满。
对于大型集合（250+产品），分页会自动执行但会增加执行时间，建议在非高峰时段运行。
本技能仅读取产品节点的
```
totalInventory
```
——不会按位置聚合。如果你需要按特定位置排序，请使用
```
low-inventory-restock
```
技能来确定要优先处理的产品。