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

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the latest version of the GraphQL Admin API or higher.
• Your app has the write_products access scope. Learn how to configure your access scopes using Shopify CLI.
• You've created a collection with products to reorder.

Anchor to How it worksHow 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.

Anchor to Step 1: Move products in the collectionStep 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 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.

Anchor to Move multiple productsMove 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.

Anchor to Move a product to the endMove 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).

Anchor to Step 2: Check the job statusStep 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.

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.

Anchor to Handling large collectionsHandling 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.

Anchor to Next stepsNext steps

• Learn how to add product data.
• Learn how to update product data.
• Explore the collectionReorderProducts mutation and Collection object in the GraphQL Admin API reference.