---
title: Reorder products in collections
description: Learn how to reorder products within a collection using the GraphQL Admin API.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products
  md: >-
    https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#requirements)
* [How it works](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#how-it-works)
* [Step 1: Move products in the collection](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#step-1-move-products-in-the-collection)
* [Step 2: Check the job status](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#step-2-check-the-job-status)
* [Handling large collections](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#handling-large-collections)
* [Next steps](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#next-steps)

# Reorder products in collections

Product order is a key merchandising tool that controls which products customers see first in collection pages, search results, and product recommendations. Merchants use product order to highlight new arrivals, promote seasonal items, or prioritize best sellers.

This guide shows how to reorder products in collections using the [`collectionReorderProducts`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionReorderProducts) mutation.

***

## Requirements

* Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the latest version of the GraphQL Admin API or higher.
* Your app has the `write_products` [access scope](https://shopify.dev/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration).
* You've [created a collection](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionCreate) with products to reorder.

***

## How it works

You specify which products to move and their new positions, and the API handles the rest. For example, to move a product to the top of a 500-product collection, send one move instruction. The API automatically adjusts all other products.

The mutation uses zero-based indexing (position 0 is first), processes moves sequentially, and returns a job ID to poll for completion. You can move up to 250 products in a single request.

***

## Step 1: Move products in the collection

Product position in a collection directly impacts customer experience because products at the top get more visibility and clicks. Use [`collectionReorderProducts`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionReorderProducts) to control this order programmatically. The mutation uses zero-based indexing (position 0 is the first product).

The following example shows how to move a single product to position 4. This is useful for promoting specific products (like new arrivals or sale items) without manually reordering the entire collection. The API automatically adjusts other products to accommodate the move.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation ReorderProducts {
  collectionReorderProducts(
    id: "gid://shopify/Collection/1234567890",
    # Specify only the products whose positions are changing.
    # The API automatically adjusts other products.
    moves: [
      {
        id: "gid://shopify/Product/9876543210",
        # Move this product to position 4 (fifth position, zero-indexed).
        newPosition: 4
      }
    ]
  ) {
    job {
      # Use this job ID to poll for completion.
      id
      # Initially false. Poll until this becomes true.
      done
    }
    userErrors {
      field
      message
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "collectionReorderProducts": {
      "job": {
        "id": "gid://shopify/Job/abc123",
        "done": false
      },
      "userErrors": []
    }
  }
}
```

### Move multiple products

The following example shows how to move two products: product X to the front (position 0) and product Y to position 10.

Moves are processed sequentially: product X moves first (shifting all products down), then product Y moves to position 10 (accounting for the shift from the first move). You can batch up to 250 moves in a single request.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation ReorderMultipleProducts {
  collectionReorderProducts(
    id: "gid://shopify/Collection/1234567890",
    # Multiple moves are processed sequentially in the order provided.
    moves: [
      {
        id: "gid://shopify/Product/111",
        # Move to position 0 (first product).
        newPosition: 0
      },
      {
        id: "gid://shopify/Product/222",
        # Move to position 10. This is evaluated after the first move.
        newPosition: 10
      }
    ]
  ) {
    job {
      id
      done
    }
    userErrors {
      field
      message
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "collectionReorderProducts": {
      "job": {
        "id": "gid://shopify/Job/def456",
        "done": false
      },
      "userErrors": []
    }
  }
}
```

### Move a product to the end

The following example shows how to move a product to the end by setting `newPosition` to 9999.

If `newPosition` is greater than or equal to the total number of products, the product moves to the end. For example, if the collection has 100 products, setting the position to 100, 999, or any value ≥ 100 places the product at the end (actual position 99, since positions are zero-indexed).

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation MoveProductToEnd {
  collectionReorderProducts(
    id: "gid://shopify/Collection/1234567890",
    moves: [
      {
        id: "gid://shopify/Product/111",
        # Setting to a value >= total products moves it to the end.
        newPosition: 9999
      }
    ]
  ) {
    job {
      id
      done
    }
    userErrors {
      field
      message
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "collectionReorderProducts": {
      "job": {
        "id": "gid://shopify/Job/ghi789",
        "done": false
      },
      "userErrors": []
    }
  }
}
```

***

## Step 2: Check the job status

Because reordering is asynchronous, you need to poll to know when it completes. This prevents your app from displaying stale product orders to users or attempting further operations before the reorder finishes. Polling ensures your app stays in sync with the actual collection state.

To check when the reorder operation completes, poll the job using the ID returned from [Step 1](#step-1-move-products-in-the-collection).

The following example shows how to query the job status. Poll every 1-2 seconds until `done` becomes `true`, indicating the collection has been reordered and customers will see the new product order.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query CheckJob {
  # Use the job ID returned from the collectionReorderProducts mutation.
  job(id: "gid://shopify/Job/abc123") {
    id
    # Poll until done is true, indicating the reorder is complete.
    done
  }
}
```

## JSON response (when complete)

```json
{
  "data": {
    "job": {
      "id": "gid://shopify/Job/abc123",
      "done": true
    }
  }
}
```

***

## Handling large collections

For collections with more than 250 products that need repositioning, split moves into batches of 250 or fewer. Send the first batch and poll until complete, then send subsequent batches sequentially. Wait for each job to complete before sending the next batch because sending batches simultaneously can cause conflicts and unpredictable results.

If your app allows multiple users to reorder the same collection simultaneously, queue reorder requests for each collection and process one at a time to avoid conflicts.

***

## Next steps

* Learn how to [add product data](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/add-data).
* Learn how to [update product data](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/update-data).
* Explore the [`collectionReorderProducts`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionReorderProducts) mutation and [`Collection`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection) object in the GraphQL Admin API reference.

***

* [Requirements](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#requirements)
* [How it works](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#how-it-works)
* [Step 1: Move products in the collection](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#step-1-move-products-in-the-collection)
* [Step 2: Check the job status](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#step-2-check-the-job-status)
* [Handling large collections](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#handling-large-collections)
* [Next steps](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/reorder-products.md#next-steps)