Choose a version:

productCreateMedia

mutation

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

Deprecated. Use productUpdate or productSet instead.

Adds media files to a Product, such as images, videos, or 3D models. Media files enhance product listings by providing visual representations that help customers understand the product.

The mutation accepts an array of CreateMediaInput objects, each specifying the source URL, content type, and optional alt text.

You can add multiple media files in a single request. The mutation adds all valid files and returns errors for any invalid ones.

Anchor to Arguments

Arguments

Anchor to mediamedia

•[CreateMediaInput!]!

required

List of new media to be added to a product.

Anchor to productIdproductId

•ID!

required

Specifies the product associated with the media.

Was this section helpful?

Anchor to ProductCreateMediaPayload returnsProductCreateMediaPayload returns

Anchor to mediamedia •[Media!]: The newly created media.
Anchor to mediaUserErrorsmediaUserErrors •[MediaUserError!]! non-null: The list of errors that occurred from executing the mutation.
Anchor to productproduct •Product: The product associated with the media.
Anchor to userErrorsuserErrors •[UserError!]! non-nullDeprecated: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Add both valid and invalid media to an existing product

Description

Trying to add both valid and invalid media to a product adds the valid media and returns an error for the invalid media.

Query

mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}

Variables

{
  "media": [
    {
      "alt": "Image",
      "mediaContentType": "EXTERNAL_VIDEO",
      "originalSource": "https://youtu.be/32mGBDk3LSo"
    },
    {
      "alt": "Image",
      "mediaContentType": "IMAGE",
      "originalSource": "invalid_img"
    }
  ],
  "productId": "gid://shopify/Product/121709582"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) { productCreateMedia(media: $media, productId: $productId) { media { alt mediaContentType status } mediaUserErrors { field message } product { id title } } }",
 "variables": {
    "media": [
      {
        "alt": "Image",
        "mediaContentType": "EXTERNAL_VIDEO",
        "originalSource": "https://youtu.be/32mGBDk3LSo"
      },
      {
        "alt": "Image",
        "mediaContentType": "IMAGE",
        "originalSource": "invalid_img"
      }
    ],
    "productId": "gid://shopify/Product/121709582"
  }
}'

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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }`,
  {
    variables: {
        "media": [
            {
                "alt": "Image",
                "mediaContentType": "EXTERNAL_VIDEO",
                "originalSource": "https://youtu.be/32mGBDk3LSo"
            },
            {
                "alt": "Image",
                "mediaContentType": "IMAGE",
                "originalSource": "invalid_img"
            }
        ],
        "productId": "gid://shopify/Product/121709582"
    },
  },
  );
  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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }
QUERY

variables = {
  "media": [
    {
      "alt": "Image",
      "mediaContentType": "EXTERNAL_VIDEO",
      "originalSource": "https://youtu.be/32mGBDk3LSo"
    },
    {
      "alt": "Image",
      "mediaContentType": "IMAGE",
      "originalSource": "invalid_img"
    }
  ],
  "productId": "gid://shopify/Product/121709582"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
      productCreateMedia(media: $media, productId: $productId) {
        media {
          alt
          mediaContentType
          status
        }
        mediaUserErrors {
          field
          message
        }
        product {
          id
          title
        }
      }
    }`,
    "variables": {
        "media": [
            {
                "alt": "Image",
                "mediaContentType": "EXTERNAL_VIDEO",
                "originalSource": "https://youtu.be/32mGBDk3LSo"
            },
            {
                "alt": "Image",
                "mediaContentType": "IMAGE",
                "originalSource": "invalid_img"
            }
        ],
        "productId": "gid://shopify/Product/121709582"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}' \
--variables \
'{
  "media": [
    {
      "alt": "Image",
      "mediaContentType": "EXTERNAL_VIDEO",
      "originalSource": "https://youtu.be/32mGBDk3LSo"
    },
    {
      "alt": "Image",
      "mediaContentType": "IMAGE",
      "originalSource": "invalid_img"
    }
  ],
  "productId": "gid://shopify/Product/121709582"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
        productCreateMedia(media: $media, productId: $productId) {
          media {
            alt
            mediaContentType
            status
          }
          mediaUserErrors {
            field
            message
          }
          product {
            id
            title
          }
        }
      }
    `,
    variables: {
        "media": [
            {
                "alt": "Image",
                "mediaContentType": "EXTERNAL_VIDEO",
                "originalSource": "https://youtu.be/32mGBDk3LSo"
            },
            {
                "alt": "Image",
                "mediaContentType": "IMAGE",
                "originalSource": "invalid_img"
            }
        ],
        "productId": "gid://shopify/Product/121709582"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "productCreateMedia": {
    "media": [
      {
        "alt": "Image",
        "mediaContentType": "EXTERNAL_VIDEO",
        "status": "UPLOADED"
      }
    ],
    "mediaUserErrors": [
      {
        "field": [
          "media",
          "1",
          "originalSource"
        ],
        "message": "Image URL is invalid"
      }
    ],
    "product": {
      "id": "gid://shopify/Product/121709582",
      "title": "Boots"
    }
  }
}

Add invalid media to an existing product

Description

Trying to add invalid media to a product returns an error.

Query

mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}

Variables

{
  "media": {
    "alt": "Image",
    "mediaContentType": "IMAGE",
    "originalSource": "invalid_img"
  },
  "productId": "gid://shopify/Product/121709582"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) { productCreateMedia(media: $media, productId: $productId) { media { alt mediaContentType status } mediaUserErrors { field message } product { id title } } }",
 "variables": {
    "media": {
      "alt": "Image",
      "mediaContentType": "IMAGE",
      "originalSource": "invalid_img"
    },
    "productId": "gid://shopify/Product/121709582"
  }
}'

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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }`,
  {
    variables: {
        "media": {
            "alt": "Image",
            "mediaContentType": "IMAGE",
            "originalSource": "invalid_img"
        },
        "productId": "gid://shopify/Product/121709582"
    },
  },
  );
  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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }
QUERY

variables = {
  "media": {
    "alt": "Image",
    "mediaContentType": "IMAGE",
    "originalSource": "invalid_img"
  },
  "productId": "gid://shopify/Product/121709582"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
      productCreateMedia(media: $media, productId: $productId) {
        media {
          alt
          mediaContentType
          status
        }
        mediaUserErrors {
          field
          message
        }
        product {
          id
          title
        }
      }
    }`,
    "variables": {
        "media": {
            "alt": "Image",
            "mediaContentType": "IMAGE",
            "originalSource": "invalid_img"
        },
        "productId": "gid://shopify/Product/121709582"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}' \
--variables \
'{
  "media": {
    "alt": "Image",
    "mediaContentType": "IMAGE",
    "originalSource": "invalid_img"
  },
  "productId": "gid://shopify/Product/121709582"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
        productCreateMedia(media: $media, productId: $productId) {
          media {
            alt
            mediaContentType
            status
          }
          mediaUserErrors {
            field
            message
          }
          product {
            id
            title
          }
        }
      }
    `,
    variables: {
        "media": {
            "alt": "Image",
            "mediaContentType": "IMAGE",
            "originalSource": "invalid_img"
        },
        "productId": "gid://shopify/Product/121709582"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "productCreateMedia": {
    "media": [],
    "mediaUserErrors": [
      {
        "field": [
          "media",
          "0",
          "originalSource"
        ],
        "message": "Image URL is invalid"
      }
    ],
    "product": {
      "id": "gid://shopify/Product/121709582",
      "title": "Boots"
    }
  }
}

Add new media to a non-existent product

Description

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

Query

mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}

Variables

{
  "media": {
    "alt": "Video",
    "mediaContentType": "EXTERNAL_VIDEO",
    "originalSource": "https://youtu.be/32mGBDk3LSo"
  },
  "productId": "gid://shopify/Product/-1"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) { productCreateMedia(media: $media, productId: $productId) { media { alt mediaContentType status } mediaUserErrors { field message } product { id title } } }",
 "variables": {
    "media": {
      "alt": "Video",
      "mediaContentType": "EXTERNAL_VIDEO",
      "originalSource": "https://youtu.be/32mGBDk3LSo"
    },
    "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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }`,
  {
    variables: {
        "media": {
            "alt": "Video",
            "mediaContentType": "EXTERNAL_VIDEO",
            "originalSource": "https://youtu.be/32mGBDk3LSo"
        },
        "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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }
QUERY

variables = {
  "media": {
    "alt": "Video",
    "mediaContentType": "EXTERNAL_VIDEO",
    "originalSource": "https://youtu.be/32mGBDk3LSo"
  },
  "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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
      productCreateMedia(media: $media, productId: $productId) {
        media {
          alt
          mediaContentType
          status
        }
        mediaUserErrors {
          field
          message
        }
        product {
          id
          title
        }
      }
    }`,
    "variables": {
        "media": {
            "alt": "Video",
            "mediaContentType": "EXTERNAL_VIDEO",
            "originalSource": "https://youtu.be/32mGBDk3LSo"
        },
        "productId": "gid://shopify/Product/-1"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}' \
--variables \
'{
  "media": {
    "alt": "Video",
    "mediaContentType": "EXTERNAL_VIDEO",
    "originalSource": "https://youtu.be/32mGBDk3LSo"
  },
  "productId": "gid://shopify/Product/-1"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
        productCreateMedia(media: $media, productId: $productId) {
          media {
            alt
            mediaContentType
            status
          }
          mediaUserErrors {
            field
            message
          }
          product {
            id
            title
          }
        }
      }
    `,
    variables: {
        "media": {
            "alt": "Video",
            "mediaContentType": "EXTERNAL_VIDEO",
            "originalSource": "https://youtu.be/32mGBDk3LSo"
        },
        "productId": "gid://shopify/Product/-1"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

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

Add new media to an existing product

Query

mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}

Variables

{
  "media": {
    "alt": "Video",
    "mediaContentType": "EXTERNAL_VIDEO",
    "originalSource": "https://youtu.be/32mGBDk3LSo"
  },
  "productId": "gid://shopify/Product/121709582"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) { productCreateMedia(media: $media, productId: $productId) { media { alt mediaContentType status } mediaUserErrors { field message } product { id title } } }",
 "variables": {
    "media": {
      "alt": "Video",
      "mediaContentType": "EXTERNAL_VIDEO",
      "originalSource": "https://youtu.be/32mGBDk3LSo"
    },
    "productId": "gid://shopify/Product/121709582"
  }
}'

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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }`,
  {
    variables: {
        "media": {
            "alt": "Video",
            "mediaContentType": "EXTERNAL_VIDEO",
            "originalSource": "https://youtu.be/32mGBDk3LSo"
        },
        "productId": "gid://shopify/Product/121709582"
    },
  },
  );
  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 productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
    productCreateMedia(media: $media, productId: $productId) {
      media {
        alt
        mediaContentType
        status
      }
      mediaUserErrors {
        field
        message
      }
      product {
        id
        title
      }
    }
  }
QUERY

variables = {
  "media": {
    "alt": "Video",
    "mediaContentType": "EXTERNAL_VIDEO",
    "originalSource": "https://youtu.be/32mGBDk3LSo"
  },
  "productId": "gid://shopify/Product/121709582"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
      productCreateMedia(media: $media, productId: $productId) {
        media {
          alt
          mediaContentType
          status
        }
        mediaUserErrors {
          field
          message
        }
        product {
          id
          title
        }
      }
    }`,
    "variables": {
        "media": {
            "alt": "Video",
            "mediaContentType": "EXTERNAL_VIDEO",
            "originalSource": "https://youtu.be/32mGBDk3LSo"
        },
        "productId": "gid://shopify/Product/121709582"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
  productCreateMedia(media: $media, productId: $productId) {
    media {
      alt
      mediaContentType
      status
    }
    mediaUserErrors {
      field
      message
    }
    product {
      id
      title
    }
  }
}' \
--variables \
'{
  "media": {
    "alt": "Video",
    "mediaContentType": "EXTERNAL_VIDEO",
    "originalSource": "https://youtu.be/32mGBDk3LSo"
  },
  "productId": "gid://shopify/Product/121709582"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation productCreateMedia($media: [CreateMediaInput!]!, $productId: ID!) {
        productCreateMedia(media: $media, productId: $productId) {
          media {
            alt
            mediaContentType
            status
          }
          mediaUserErrors {
            field
            message
          }
          product {
            id
            title
          }
        }
      }
    `,
    variables: {
        "media": {
            "alt": "Video",
            "mediaContentType": "EXTERNAL_VIDEO",
            "originalSource": "https://youtu.be/32mGBDk3LSo"
        },
        "productId": "gid://shopify/Product/121709582"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "productCreateMedia": {
    "media": [
      {
        "alt": "Video",
        "mediaContentType": "EXTERNAL_VIDEO",
        "status": "UPLOADED"
      }
    ],
    "mediaUserErrors": [],
    "product": {
      "id": "gid://shopify/Product/121709582",
      "title": "Boots"
    }
  }
}

Create a new Product Image

Query

mutation ProductImageCreate($id: ID!) {
  productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
    media {
      id
      alt
      status
      ... on MediaImage {
        image {
          url
        }
      }
    }
    mediaUserErrors {
      field
      message
    }
  }
}

Variables

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation ProductImageCreate($id: ID!) { productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: \"https://path.to/image.jpg\", alt: \"Alt text.\"}]) { media { id alt status ... on MediaImage { image { url } } } mediaUserErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Product/121709582"
  }
}'

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 ProductImageCreate($id: ID!) {
    productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/121709582"
    },
  },
  );
  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 ProductImageCreate($id: ID!) {
    productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }
QUERY

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

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation ProductImageCreate($id: ID!) {
      productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
        media {
          id
          alt
          status
          ... on MediaImage {
            image {
              url
            }
          }
        }
        mediaUserErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/121709582"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation ProductImageCreate($id: ID!) {
  productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
    media {
      id
      alt
      status
      ... on MediaImage {
        image {
          url
        }
      }
    }
    mediaUserErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Product/121709582"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation ProductImageCreate($id: ID!) {
        productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
          media {
            id
            alt
            status
            ... on MediaImage {
              image {
                url
              }
            }
          }
          mediaUserErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Product/121709582"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "productCreateMedia": {
    "media": [
      {
        "id": "gid://shopify/MediaImage/1072273196",
        "alt": "Alt text.",
        "status": "UPLOADED",
        "image": null
      }
    ],
    "mediaUserErrors": []
  }
}

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

productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {

media {

alt

status

... on MediaImage {

image {

url

}

mediaUserErrors {

field

message

}

}`,

{

variables: {

"id": "gid://shopify/Product/121709582"

);

const json = await response.json();

return json.data;

}

GQL

mutation ProductImageCreate($id: ID!) {
  productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "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/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation ProductImageCreate($id: ID!) { productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: \"https://path.to/image.jpg\", alt: \"Alt text.\"}]) { media { id alt status ... on MediaImage { image { url } } } mediaUserErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Product/121709582"
  }
}'

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 ProductImageCreate($id: ID!) {
    productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/121709582"
    },
  },
  );
  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 ProductImageCreate($id: ID!) {
      productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
        media {
          id
          alt
          status
          ... on MediaImage {
            image {
              url
            }
          }
        }
        mediaUserErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/121709582"
    },
  },
});

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 ProductImageCreate($id: ID!) {
    productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
      media {
        id
        alt
        status
        ... on MediaImage {
          image {
            url
          }
        }
      }
      mediaUserErrors {
        field
        message
      }
    }
  }
QUERY

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

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

Shopify CLI

shopify app execute \
--query \
'mutation ProductImageCreate($id: ID!) {
  productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
    media {
      id
      alt
      status
      ... on MediaImage {
        image {
          url
        }
      }
    }
    mediaUserErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Product/121709582"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation ProductImageCreate($id: ID!) {
        productCreateMedia(productId: $id, media: [{mediaContentType: IMAGE, originalSource: "https://path.to/image.jpg", alt: "Alt text."}]) {
          media {
            id
            alt
            status
            ... on MediaImage {
              image {
                url
              }
            }
          }
          mediaUserErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Product/121709582"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"id": "gid://shopify/Product/121709582"

}

Response

JSON

{

"productCreateMedia": {

"media": [

{

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

"alt": "Alt text.",

"status": "UPLOADED",

"image": null

}

"mediaUserErrors": []

}