Choose a version:

productReorderMedia

mutation

Requires write_products access scope. Also: The user must have a permission to reorder the media attached to a product.

Reorders media attached to a product, changing their sequence in product displays. The operation processes asynchronously to handle products with large media collections.

Specify the product ID and an array of moves, where each move contains a media ID and its new zero-based position.

Note

Only include media items that need repositioning. Unchanged items maintain their relative order automatically.

The mutation returns a Job to track the reordering progress. Poll the job status to determine when the operation completes and media positions update across all sales channels.

Learn more about reordering product media.

Anchor to Arguments

Arguments

Anchor to idid

•ID!

required

The ID of the product on which to reorder medias.

Anchor to movesmoves

•[MoveInput!]!

required

A list of moves to perform which will be evaluated in order.

Was this section helpful?

Anchor to ProductReorderMediaPayload returnsProductReorderMediaPayload returns

Anchor to jobjob •Job: The asynchronous job which reorders the media.
Anchor to mediaUserErrorsmediaUserErrors •[MediaUserError!]! non-null: The list of errors that occurred from executing the mutation.
Anchor to userErrorsuserErrors •[UserError!]! non-nullDeprecated: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Reorder a product's media

Description

Update the order of a product's media

Query

mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {
  productReorderMedia(id: $id, moves: $moves) {
    job {
      id
    }
  }
}

Variables

{
  "id": "gid://shopify/Product/108828309",
  "moves": [
    {
      "id": "gid://shopify/MediaImage/183532652",
      "newPosition": "2"
    },
    {
      "id": "gid://shopify/MediaImage/731367280",
      "newPosition": "3"
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) { productReorderMedia(id: $id, moves: $moves) { job { id } } }",
 "variables": {
    "id": "gid://shopify/Product/108828309",
    "moves": [
      {
        "id": "gid://shopify/MediaImage/183532652",
        "newPosition": "2"
      },
      {
        "id": "gid://shopify/MediaImage/731367280",
        "newPosition": "3"
      }
    ]
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {
    productReorderMedia(id: $id, moves: $moves) {
      job {
        id
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/108828309",
        "moves": [
            {
                "id": "gid://shopify/MediaImage/183532652",
                "newPosition": "2"
            },
            {
                "id": "gid://shopify/MediaImage/731367280",
                "newPosition": "3"
            }
        ]
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {
    productReorderMedia(id: $id, moves: $moves) {
      job {
        id
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/108828309",
  "moves": [
    {
      "id": "gid://shopify/MediaImage/183532652",
      "newPosition": "2"
    },
    {
      "id": "gid://shopify/MediaImage/731367280",
      "newPosition": "3"
    }
  ]
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {
      productReorderMedia(id: $id, moves: $moves) {
        job {
          id
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/108828309",
        "moves": [
            {
                "id": "gid://shopify/MediaImage/183532652",
                "newPosition": "2"
            },
            {
                "id": "gid://shopify/MediaImage/731367280",
                "newPosition": "3"
            }
        ]
    },
  },
});

Response

{
  "productReorderMedia": {
    "job": {
      "id": "gid://shopify/Job/6dfa599a-a426-4030-8f10-6564abc465f9"
    }
  }
}

productReorderMedia reference

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {

productReorderMedia(id: $id, moves: $moves) {

job {

}

}`,

{

variables: {

"id": "gid://shopify/Product/108828309",

"moves": [

{

"id": "gid://shopify/MediaImage/183532652",

"newPosition": "2"

{

"id": "gid://shopify/MediaImage/731367280",

"newPosition": "3"

}

]

);

const json = await response.json();

return json.data;

}

GQL

mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {
  productReorderMedia(id: $id, moves: $moves) {
    job {
      id
    }
  }
}