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

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

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

Inputs: id: , moves array sorted by totalInventory per sort_by parameter — each move is {id: , newPosition: ""} (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