Choose a version:

productVariantAppendMedia

mutation

Requires write_products access scope. Also: The user must have a permission to append media to variants.

Appends existing media from a product to specific variants of that product, creating associations between media files and particular product options. This allows different variants to showcase relevant images or videos.

For example, a t-shirt product might have color variants where each color variant displays only the images showing that specific color, helping customers see exactly what they're purchasing.

Use ProductVariantAppendMedia to:

Associate specific images with product variants for accurate display
Build variant-specific media management in product interfaces
Implement automated media assignment based on variant attributes

The operation links existing product media to variants without duplicating files, maintaining efficient media storage while enabling variant-specific displays.

Learn more about product variants.

Anchor to Arguments

Arguments

Anchor to productIdproductId •ID! required: Specifies the product associated to the media.
Anchor to variantMediavariantMedia •[ProductVariantAppendMediaInput!]! required: A list of pairs of variants and media to be attached to the variants.

Was this section helpful?

Anchor to ProductVariantAppendMediaPayload returnsProductVariantAppendMediaPayload returns

Anchor to productproduct •Product: The product associated with the variants and media.
Anchor to productVariantsproductVariants •[ProductVariant!]: The product variants that were updated.
Anchor to userErrorsuserErrors •[MediaUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Append a product's media to variants of the product

Description

Append media of a product to the product's variants

Query

mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
  productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
    product {
      id
    }
  }
}

Variables

{
  "productId": "gid://shopify/Product/1072481072",
  "variantMedia": [
    {
      "mediaIds": [
        "gid://shopify/MediaImage/1072273216"
      ],
      "variantId": "gid://shopify/ProductVariant/1070325119"
    },
    {
      "mediaIds": [
        "gid://shopify/MediaImage/1072273217"
      ],
      "variantId": "gid://shopify/ProductVariant/1070325120"
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) { productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) { product { id } } }",
 "variables": {
    "productId": "gid://shopify/Product/1072481072",
    "variantMedia": [
      {
        "mediaIds": [
          "gid://shopify/MediaImage/1072273216"
        ],
        "variantId": "gid://shopify/ProductVariant/1070325119"
      },
      {
        "mediaIds": [
          "gid://shopify/MediaImage/1072273217"
        ],
        "variantId": "gid://shopify/ProductVariant/1070325120"
      }
    ]
  }
}'

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 productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
    productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
      product {
        id
      }
    }
  }`,
  {
    variables: {
        "productId": "gid://shopify/Product/1072481072",
        "variantMedia": [
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273216"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325119"
            },
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273217"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325120"
            }
        ]
    },
  },
  );
  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 productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
    productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
      product {
        id
      }
    }
  }
QUERY

variables = {
  "productId": "gid://shopify/Product/1072481072",
  "variantMedia": [
    {
      "mediaIds": [
        "gid://shopify/MediaImage/1072273216"
      ],
      "variantId": "gid://shopify/ProductVariant/1070325119"
    },
    {
      "mediaIds": [
        "gid://shopify/MediaImage/1072273217"
      ],
      "variantId": "gid://shopify/ProductVariant/1070325120"
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
      productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
        product {
          id
        }
      }
    }`,
    "variables": {
        "productId": "gid://shopify/Product/1072481072",
        "variantMedia": [
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273216"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325119"
            },
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273217"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325120"
            }
        ]
    },
  },
});

Response

{
  "productVariantAppendMedia": {
    "product": {
      "id": "gid://shopify/Product/1072481072"
    }
  }
}

productVariantAppendMedia 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 productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {

productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {

product {

}

}`,

{

variables: {

"productId": "gid://shopify/Product/1072481072",

"variantMedia": [

{

"mediaIds": [

"gid://shopify/MediaImage/1072273216"

"variantId": "gid://shopify/ProductVariant/1070325119"

{

"mediaIds": [

"gid://shopify/MediaImage/1072273217"

"variantId": "gid://shopify/ProductVariant/1070325120"

}

]

);

const json = await response.json();

return json.data;

}

mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
  productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
    product {
      id
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) { productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) { product { id } } }",
 "variables": {
    "productId": "gid://shopify/Product/1072481072",
    "variantMedia": [
      {
        "mediaIds": [
          "gid://shopify/MediaImage/1072273216"
        ],
        "variantId": "gid://shopify/ProductVariant/1070325119"
      },
      {
        "mediaIds": [
          "gid://shopify/MediaImage/1072273217"
        ],
        "variantId": "gid://shopify/ProductVariant/1070325120"
      }
    ]
  }
}'

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
    productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
      product {
        id
      }
    }
  }`,
  {
    variables: {
        "productId": "gid://shopify/Product/1072481072",
        "variantMedia": [
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273216"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325119"
            },
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273217"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325120"
            }
        ]
    },
  },
  );
  const json = await response.json();
  return json.data;
}

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
      productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
        product {
          id
        }
      }
    }`,
    "variables": {
        "productId": "gid://shopify/Product/1072481072",
        "variantMedia": [
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273216"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325119"
            },
            {
                "mediaIds": [
                    "gid://shopify/MediaImage/1072273217"
                ],
                "variantId": "gid://shopify/ProductVariant/1070325120"
            }
        ]
    },
  },
});

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 productVariantAppendMedia($productId: ID!, $variantMedia: [ProductVariantAppendMediaInput!]!) {
    productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
      product {
        id
      }
    }
  }
QUERY

variables = {
  "productId": "gid://shopify/Product/1072481072",
  "variantMedia": [
    {
      "mediaIds": [
        "gid://shopify/MediaImage/1072273216"
      ],
      "variantId": "gid://shopify/ProductVariant/1070325119"
    },
    {
      "mediaIds": [
        "gid://shopify/MediaImage/1072273217"
      ],
      "variantId": "gid://shopify/ProductVariant/1070325120"
    }
  ]
}

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

Input variables

JSON

{

"productId": "gid://shopify/Product/1072481072",

"variantMedia": [

{

"mediaIds": [

"gid://shopify/MediaImage/1072273216"

"variantId": "gid://shopify/ProductVariant/1070325119"

{

"mediaIds": [

"gid://shopify/MediaImage/1072273217"

"variantId": "gid://shopify/ProductVariant/1070325120"

}

]

}

Response

JSON

{

"productVariantAppendMedia": {

"product": {

"id": "gid://shopify/Product/1072481072"

}