Choose a version:

productUpdateMedia

mutation

Requires write_products access scope. Also: The user must have a permission to update media for a product.

Deprecated. Use fileUpdate instead.

Updates properties of media attached to a Product. You can modify alt text for accessibility or change preview images for existing media items.

Provide the product ID and an array of UpdateMediaInput objects. Each update specifies the media's ID and the properties to change. Updates apply only to media already attached to the product and don't affect their position in the product gallery.

Anchor to Arguments

Arguments

Anchor to mediamedia

•[UpdateMediaInput!]!

required

A list of media updates.

Anchor to productIdproductId

•ID!

required

Specifies the product on which media will be updated.

Was this section helpful?

Anchor to ProductUpdateMediaPayload returnsProductUpdateMediaPayload returns

Anchor to mediamedia •[Media!]: The updated media object.
Anchor to mediaUserErrorsmediaUserErrors •[MediaUserError!]! non-null: The list of errors that occurred from executing the mutation.
Anchor to productproduct •Product: The product on which media was updated.
Anchor to userErrorsuserErrors •[UserError!]! non-nullDeprecated: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Modify an existing Product Image

Query

mutation ProductImageUpdate($id: ID!) {
  productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
    media {
      id
      alt
      status
      ... on MediaImage {
        image {
          url
        }
      }
    }
    mediaUserErrors {
      field
      message
    }
  }
}

Variables

{
  "id": "gid://shopify/Product/108828309"
}

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 ProductImageUpdate($id: ID!) { productUpdateMedia(productId: $id, media: [{id: \"gid://shopify/MediaImage/853695510\", alt: \"Updated alt text.\"}]) { media { id alt status ... on MediaImage { image { url } } } mediaUserErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Product/108828309"
  }
}'

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 ProductImageUpdate($id: ID!) {
    productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/108828309"
    },
  },
  );
  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 ProductImageUpdate($id: ID!) {
    productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/108828309"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation ProductImageUpdate($id: ID!) {
      productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
        media {
          id
          alt
          status
          ... on MediaImage {
            image {
              url
            }
          }
        }
        mediaUserErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/108828309"
    },
  },
});

Response

{
  "productUpdateMedia": {
    "media": [
      {
        "id": "gid://shopify/MediaImage/853695510",
        "alt": "Updated alt text.",
        "status": "READY",
        "image": {
          "url": "https://cdn.shopify.com/s/files/1/2637/1970/products/draft58.jpg?v=1730761095"
        }
      }
    ],
    "mediaUserErrors": []
  }
}

Update a product's media fields

Description

Update the media fields of a product

Query

mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
  productUpdateMedia(media: $media, productId: $productId) {
    media {
      alt
    }
  }
}

Variables

{
  "media": [
    {
      "alt": "Some alt text",
      "id": "gid://shopify/Video/723685877"
    },
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/853695510"
    }
  ],
  "productId": "gid://shopify/Product/108828309"
}

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) { productUpdateMedia(media: $media, productId: $productId) { media { alt } } }",
 "variables": {
    "media": [
      {
        "alt": "Some alt text",
        "id": "gid://shopify/Video/723685877"
      },
      {
        "alt": "Some more alt text",
        "id": "gid://shopify/MediaImage/853695510"
      }
    ],
    "productId": "gid://shopify/Product/108828309"
  }
}'

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      media {
        alt
      }
    }
  }`,
  {
    variables: {
        "media": [
            {
                "alt": "Some alt text",
                "id": "gid://shopify/Video/723685877"
            },
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/853695510"
            }
        ],
        "productId": "gid://shopify/Product/108828309"
    },
  },
  );
  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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      media {
        alt
      }
    }
  }
QUERY

variables = {
  "media": [
    {
      "alt": "Some alt text",
      "id": "gid://shopify/Video/723685877"
    },
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/853695510"
    }
  ],
  "productId": "gid://shopify/Product/108828309"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
      productUpdateMedia(media: $media, productId: $productId) {
        media {
          alt
        }
      }
    }`,
    "variables": {
        "media": [
            {
                "alt": "Some alt text",
                "id": "gid://shopify/Video/723685877"
            },
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/853695510"
            }
        ],
        "productId": "gid://shopify/Product/108828309"
    },
  },
});

Response

{
  "productUpdateMedia": {
    "media": [
      {
        "alt": "Some alt text"
      },
      {
        "alt": "Some more alt text"
      }
    ]
  }
}

Update new media on a non-existent product

Description

Trying to update media on a non-existent product returns an error.

Query

mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
  productUpdateMedia(media: $media, productId: $productId) {
    product {
      id
      title
    }
    media {
      alt
    }
    mediaUserErrors {
      field
      message
    }
  }
}

Variables

{
  "media": [
    {
      "alt": "Some alt text",
      "id": "gid://shopify/Video/723685877"
    },
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/853695510"
    }
  ],
  "productId": "gid://shopify/Product/-1"
}

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) { productUpdateMedia(media: $media, productId: $productId) { product { id title } media { alt } mediaUserErrors { field message } } }",
 "variables": {
    "media": [
      {
        "alt": "Some alt text",
        "id": "gid://shopify/Video/723685877"
      },
      {
        "alt": "Some more alt text",
        "id": "gid://shopify/MediaImage/853695510"
      }
    ],
    "productId": "gid://shopify/Product/-1"
  }
}'

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      product {
        id
        title
      }
      media {
        alt
      }
      mediaUserErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "media": [
            {
                "alt": "Some alt text",
                "id": "gid://shopify/Video/723685877"
            },
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/853695510"
            }
        ],
        "productId": "gid://shopify/Product/-1"
    },
  },
  );
  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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      product {
        id
        title
      }
      media {
        alt
      }
      mediaUserErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "media": [
    {
      "alt": "Some alt text",
      "id": "gid://shopify/Video/723685877"
    },
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/853695510"
    }
  ],
  "productId": "gid://shopify/Product/-1"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
      productUpdateMedia(media: $media, productId: $productId) {
        product {
          id
          title
        }
        media {
          alt
        }
        mediaUserErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "media": [
            {
                "alt": "Some alt text",
                "id": "gid://shopify/Video/723685877"
            },
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/853695510"
            }
        ],
        "productId": "gid://shopify/Product/-1"
    },
  },
});

Response

{
  "productUpdateMedia": {
    "product": null,
    "media": null,
    "mediaUserErrors": [
      {
        "field": [
          "productId"
        ],
        "message": "Product does not exist"
      }
    ]
  }
}

Update non-existent media on a non-existent product

Description

Trying to update non-existent media on a non-existent product returns an error.

Query

mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
  productUpdateMedia(media: $media, productId: $productId) {
    product {
      id
      title
    }
    media {
      alt
    }
    mediaUserErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "media": [
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/-1"
    }
  ],
  "productId": "gid://shopify/Product/-1"
}

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) { productUpdateMedia(media: $media, productId: $productId) { product { id title } media { alt } mediaUserErrors { field message code } } }",
 "variables": {
    "media": [
      {
        "alt": "Some more alt text",
        "id": "gid://shopify/MediaImage/-1"
      }
    ],
    "productId": "gid://shopify/Product/-1"
  }
}'

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      product {
        id
        title
      }
      media {
        alt
      }
      mediaUserErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "media": [
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/-1"
            }
        ],
        "productId": "gid://shopify/Product/-1"
    },
  },
  );
  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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      product {
        id
        title
      }
      media {
        alt
      }
      mediaUserErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "media": [
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/-1"
    }
  ],
  "productId": "gid://shopify/Product/-1"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
      productUpdateMedia(media: $media, productId: $productId) {
        product {
          id
          title
        }
        media {
          alt
        }
        mediaUserErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "media": [
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/-1"
            }
        ],
        "productId": "gid://shopify/Product/-1"
    },
  },
});

Response

{
  "productUpdateMedia": {
    "product": null,
    "media": null,
    "mediaUserErrors": [
      {
        "field": [
          "productId"
        ],
        "message": "Product does not exist",
        "code": "PRODUCT_DOES_NOT_EXIST"
      }
    ]
  }
}

Update non-existent media on a valid product

Description

Trying to update non-existent media on a valid product returns an error.

Query

mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
  productUpdateMedia(media: $media, productId: $productId) {
    product {
      id
      title
    }
    media {
      alt
    }
    mediaUserErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "media": [
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/-1"
    }
  ],
  "productId": "gid://shopify/Product/108828309"
}

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) { productUpdateMedia(media: $media, productId: $productId) { product { id title } media { alt } mediaUserErrors { field message code } } }",
 "variables": {
    "media": [
      {
        "alt": "Some more alt text",
        "id": "gid://shopify/MediaImage/-1"
      }
    ],
    "productId": "gid://shopify/Product/108828309"
  }
}'

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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      product {
        id
        title
      }
      media {
        alt
      }
      mediaUserErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "media": [
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/-1"
            }
        ],
        "productId": "gid://shopify/Product/108828309"
    },
  },
  );
  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 productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
    productUpdateMedia(media: $media, productId: $productId) {
      product {
        id
        title
      }
      media {
        alt
      }
      mediaUserErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "media": [
    {
      "alt": "Some more alt text",
      "id": "gid://shopify/MediaImage/-1"
    }
  ],
  "productId": "gid://shopify/Product/108828309"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productUpdateMedia($media: [UpdateMediaInput!]!, $productId: ID!) {
      productUpdateMedia(media: $media, productId: $productId) {
        product {
          id
          title
        }
        media {
          alt
        }
        mediaUserErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "media": [
            {
                "alt": "Some more alt text",
                "id": "gid://shopify/MediaImage/-1"
            }
        ],
        "productId": "gid://shopify/Product/108828309"
    },
  },
});

Response

{
  "productUpdateMedia": {
    "product": {
      "id": "gid://shopify/Product/108828309",
      "title": "Draft"
    },
    "media": null,
    "mediaUserErrors": [
      {
        "field": [
          "media"
        ],
        "message": "Media id gid://shopify/MediaImage/-1 does not exist",
        "code": "MEDIA_DOES_NOT_EXIST"
      }
    ]
  }
}

productUpdateMedia 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 ProductImageUpdate($id: ID!) {

productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {

media {

alt

status

... on MediaImage {

image {

url

}

mediaUserErrors {

field

message

}

}`,

{

variables: {

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

);

const json = await response.json();

return json.data;

}

GQL

mutation ProductImageUpdate($id: ID!) {
  productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
    media {
      id
      alt
      status
      ... on MediaImage {
        image {
          url
        }
      }
    }
    mediaUserErrors {
      field
      message
    }
  }
}

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 ProductImageUpdate($id: ID!) { productUpdateMedia(productId: $id, media: [{id: \"gid://shopify/MediaImage/853695510\", alt: \"Updated alt text.\"}]) { media { id alt status ... on MediaImage { image { url } } } mediaUserErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Product/108828309"
  }
}'

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 ProductImageUpdate($id: ID!) {
    productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/108828309"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation ProductImageUpdate($id: ID!) {
      productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
        media {
          id
          alt
          status
          ... on MediaImage {
            image {
              url
            }
          }
        }
        mediaUserErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/108828309"
    },
  },
});

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 ProductImageUpdate($id: ID!) {
    productUpdateMedia(productId: $id, media: [{id: "gid://shopify/MediaImage/853695510", alt: "Updated alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/108828309"
}

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

Input variables

JSON

{

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

}

Response

JSON

{

"productUpdateMedia": {

"media": [

{

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

"alt": "Updated alt text.",

"status": "READY",

"image": {

"url": "https://cdn.shopify.com/s/files/1/2637/1970/products/draft58.jpg?v=1730761095"

}

"mediaUserErrors": []

}