Shopify Admin Collection Reorganization

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.

Prerequisites

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

Parameters

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."

Workflow Steps

1. 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

2. 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

GraphQL Operations

# 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
      }
    }
  }
}

# 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
    }
  }
}

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>

If 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:

{
  "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.

Error Handling

Best Practices

1. Always run dry_run: true first — the skill will print the proposed product order so you can verify before committing. 2. collectionReorderProducts is asynchronous — job.done may be false immediately. The sort completes within a few seconds; refresh the storefront to verify. 3. Use sort_by: inventory_asc to push out-of-stock products to the bottom of the collection page, reducing customer frustration. 4. For large collections (250+ products), pagination is automatic but increases execution time. Consider running during off-peak hours. 5. 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.