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.

Asynchronously reorders the media attached to a product, changing the sequence in which images, videos, and other media appear in product displays. This affects how media is presented across all sales channels.

For example, merchants can move their best product photo to the first position or reorder images to tell a better product story, with changes appearing in storefronts once processing completes.

Use ProductReorderMedia to:

Optimize media presentation order for better customer experience
Implement drag-and-drop media management interfaces
Automate media sequencing based on performance or quality metrics

The operation processes asynchronously to handle products with large media collections without blocking other operations.

Learn more about 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/unstable/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"
      }
    ]
  }
}'

Remix

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 data = await response.json();

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

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 data = await response.json();

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/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"
      }
    ]
  }
}'

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 data = await response.json();

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"
            }
        ]
    },
  },
});

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)

Input variables

JSON

{