---
title: Manage media for product variants
description: Manage media objects on a product's variants with the GraphQL Admin API.
source_url:
  html: 'https://shopify.dev/docs/apps/build/online-store/product-variant-media'
  md: 'https://shopify.dev/docs/apps/build/online-store/product-variant-media.md'
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#requirements)
* [Step 1: Query a product and display its variants](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-1-query-a-product-and-display-its-variants)
* [Step 2: Create a product and associate media to its variant](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-2-create-a-product-and-associate-media-to-its-variant)
* [Step 3: Attach media to an existing product variant](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-3-attach-media-to-an-existing-product-variant)
* [Step 4: Remove media from a variant](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-4-remove-media-from-a-variant)
* [Next steps](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#next-steps)

# Manage media for product variants

You can use the GraphQL Admin API to add a media object of type `IMAGE` to a product's variants. For example, you can create a product, a product variant, and media object, and attach a media object to the product variant in a single step. You can also associate the product's media to its variants.

This guide shows how to manage media on product variants using the GraphQL Admin API.

***

## Requirements

* Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API.
* Your app has the `read_products` and `write_products` [access scopes](https://shopify.dev/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration).
* You've [created products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productcreate) and [product variants](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productvariantcreate) in your dev store.

***

## Step 1: Query a product and display its variants

The following query returns information about any image media objects that are attached to the variants of a product:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query {
  product(id: "gid://shopify/Product/1") {
    title
    variants(first: 10) {
      edges {
        node {
          selectedOptions {
            name
            value
          }
          media(first: 10) {
            edges {
              node {
                alt
                mediaContentType
                status
                __typename
                ... on MediaImage {
                  id
                  preview {
                    image {
                      url
                    }
                  }
                  __typename
                }
              }
            }
          }
        }
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "product": {
      "title": "Polaris Watch",
      "variants": {
        "edges": [
          {
            "node": {
              "selectedOptions": [
                {
                  "name": "Width",
                  "value": "24m"
                },
                {
                  "name": "Length",
                  "value": "30m"
                }
              ],
              "media": {
                "edges": [
                  {
                    "node": {
                      "alt": "Girl in a t-shirt",
                      "mediaContentType": "IMAGE",
                      "status": "READY",
                      "__typename": "MediaImage",
                      "id": "gid://shopify/MediaImage/42729528",
                      "preview": {
                        "image": {
                          "url": "https://cdn.shopify.com/s/files/1/1768/1717/products/StockSnap_9NPZZJCWW3_copy.jpg?v=1566862515"
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 343,
      "actualQueryCost": 46,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 954,
        "restoreRate": 50.0
      }
    }
  }
}
```

***

## Step 2: Create a product and associate media to its variant

When you create a new product using the [`productCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productcreate) mutation, you can include the `mediaSrc` attribute to specify the URL of the media to associate with the variant. This field matches one of the media `originalSource` fields that you created on the product.

When you create the variant options, make sure that you include the `options` values. These values must match the options that were set up on the product. For example, if the product has the variant options `[“Color”, “Size”]`, then each variant should have a color and a size option, like `[“Red”, “M”]`.

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation productCreate($input: ProductInput!, $media: [CreateMediaInput!]) {
  productCreate(input: $input, media: $media) {
    product {
      id
      variants(first: 10) {
        edges {
          node {
            selectedOptions {
              name
              value
            }
            media(first: 10) {
              edges {
                node {
                  ... on MediaImage {
                    id
                    alt
                    image {
                      url
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

## Variables

```json
{
 "media": [
   {
     "mediaContentType": "IMAGE",
     "originalSource": "https://cdn.come/red_t_shirt.jpg"
   },
   {
     "mediaContentType": "IMAGE",
     "originalSource": "https://cdn.come/yellow_t_shirt.jpg"
   }
 ],
 "input": {
   "title": "T-shirt",
   "options": [
     "Color", "Size"
   ],
   "variants": [
     {
       "mediaSrc": ["https://cdn.come/red_t_shirt.jpg"],
       "options": ["Red", "M"]
     },
     {
       "mediaSrc": ["https://cdn.come/red_t_shirt.jpg"],
       "options": ["Red", "L"]
     },
     {
       "mediaSrc": ["https://cdn.come/yellow_t_shirt.jpg"],
       "options": ["Yellow", "M"]
     },
     {
       "mediaSrc": ["https://cdn.come/yellow_t_shirt.jpg"],
       "options": ["Yellow", "L"]
     }
   ]
 }
}
```

## JSON response

```json
{
  "data": {
    "productCreate": {
      "product": {
        "id": "gid://shopify/Product/1",
        "variants": {
          "edges": [
            {
              "node": {
                "selectedOptions": [
                  {
                    "name": "Color",
                    "value": "Red"
                  },
                  {
                    "name": "Size",
                    "value": "M"
                  }
                ],
                "media": {
                  "edges": [
                    {
                      "node": {
                        "id": "gid://shopify/MediaImage/1489599037496",
                        "alt": "Girl in a red medium-sized t-shirt",
                        "image": null
                      }
                    }
                  ]
                }
              }
            },
            {
              "node": {
                "selectedOptions": [
                  {
                    "name": "Color",
                    "value": "Red"
                  },
                  {
                    "name": "Size",
                    "value": "L"
                  }
                ],
                "media": {
                  "edges": [
                    {
                      "node": {
                        "id": "gid://shopify/MediaImage/1489599037496",
                        "alt": "Girl in a red large-sized t-shirt",
                        "image": null
                      }
                    }
                  ]
                }
              }
            },
            {
              "node": {
                "selectedOptions": [
                  {
                    "name": "Color",
                    "value": "Yellow"
                  },
                  {
                    "name": "Size",
                    "value": "M"
                  }
                ],
                "media": {
                  "edges": [
                    {
                      "node": {
                        "id": "gid://shopify/MediaImage/1489599070264",
                        "alt": "Girl in a yellow medium-sized t-shirt",
                        "image": null
                      }
                    }
                  ]
                }
              }
            },
            {
              "node": {
                "selectedOptions": [
                  {
                    "name": "Color",
                    "value": "Yellow"
                  },
                  {
                    "name": "Size",
                    "value": "L"
                  }
                ],
                "media": {
                  "edges": [
                    {
                      "node": {
                        "id": "gid://shopify/MediaImage/1489599070264",
                        "alt": "Girl in a yellow large-sized t-shirt",
                        "image": null
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      },
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 252,
      "actualQueryCost": 36,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 964,
        "restoreRate": 50.0
      }
    }
  }
}
```

***

## Step 3: Attach media to an existing product variant

To attach a media object to an existing product variant, you must do the following:

1. Create the media on the product using the [`productCreateMedia`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productcreatemedia) mutation.
2. If the product doesn't have variants, then you must create at least one variant on the product.

Refer to the [`productCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productcreate), [`productUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productupdate), or [`productVariantCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productvariantcreate) mutations for more information.

When you have a product with a media object and variants, you can use the [`productVariantAppendMedia`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productvariantappendmedia) mutation to associate the media `id` to one or more variant `id`s, as shown in the following example mutation:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation ($variantMedia: [ProductVariantAppendMediaInput!]!) {
  productVariantAppendMedia(productId: "gid://shopify/Product/1", variantMedia: $variantMedia) {
    product {
      id
    }
    productVariants {
      media(first: 10) {
        edges {
          node {
            mediaContentType
            preview {
              image {
                url
              }
            }
          }
        }
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

## Variables

```json
{
	"variantMedia": [
		{
			"variantId": "gid://shopify/ProductVariant/1",
			"mediaIds": ["gid://shopify/MediaImage/1"]
		},
		{
			"variantId": "gid://shopify/ProductVariant/2",
			"mediaIds": ["gid://shopify/MediaImage/1"]
		},
		{
			"variantId": "gid://shopify/ProductVariant/3",
			"mediaIds": ["gid://shopify/MediaImage/2"]
		},
		{
			"variantId": "gid://shopify/ProductVariant/4",
			"mediaIds": ["gid://shopify/MediaImage/2"]
		}
	]
}
```

## JSON response

```json
{
  "data": {
    "productVariantAppendMedia": {
      "product": {
        "id": "gid://shopify/Product/1"
      },
      "productVariants": [
        {
          "media": {
            "edges": [
              {
                "node": {
                  "mediaContentType": "IMAGE",
                  "preview": {
                    "image": {
                      "url": "https://cdn.shopify.com/s/files/1/0013/1245/6760/products/istock_e4f127b277.jpg?v=151354"
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "media": {
            "edges": [
              {
                "node": {
                  "mediaContentType": "IMAGE",
                  "preview": {
                    "image": {
                      "url": "https://cdn.shopify.com/s/files/1/0013/1245/6760/products/istock_e4f127b277.jpg?v=151354"
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "media": {
            "edges": [
              {
                "node": {
                  "mediaContentType": "IMAGE",
                  "preview": {
                    "image": {
                      "url": "https://cdn.shopify.com/s/files/1/0013/1245/6760/products/istock_00004f2ea339.jpg?v=13783"
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "media": {
            "edges": [
              {
                "node": {
                  "mediaContentType": "IMAGE",
                  "preview": {
                    "image": {
                      "url": "https://cdn.shopify.com/s/files/1/0013/1245/6760/products/istock_00004f2ea339.jpg?v=13783"
                    }
                  }
                }
              }
            ]
          }
        }
      ],
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 42,
      "actualQueryCost": 30,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 970,
        "restoreRate": 50.0
      }
    }
  }
}
```

***

## Step 4: Remove media from a variant

To detach media from a variant, you can use the [`productVariantDetachMedia`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productvariantdetachmedia) mutation.

After you use the mutation, the media won't be associated with the variant anymore, but the media will still be associated with the product. You can use the `productDeleteMedia` mutation to remove the media from the product as well.

The following example demonstrates how to use the `productVariantDetachMedia` mutation to disassociate a media object from a product variant.

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation productVariantDetachMedia(
  $variantMedia: [ProductVariantDetachMediaInput!]!
) {
  productVariantDetachMedia(
    productId: "gid://shopify/Product/1"
    variantMedia: $variantMedia
  ) {
    product {
      id
    }
    productVariants {
      id
      media(first: 10) {
        edges {
          node {
            preview {
              image {
                url
              }
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

## Variables

```json
{
  "variantMedia": [
    {
      "variantId": "gid://shopify/ProductVariant/1",
      "mediaIds": [
        "gid://shopify/Media/1"
      ]
    },
    {
      "variantId": "gid://shopify/ProductVariant/2",
      "mediaIds": [
        "gid://shopify/Media/2"
      ]
    }
  ]
}
```

## JSON response

```json
{
  "data": {
    "productVariantDetachMedia": {
      "product": {
        "id": "gid://shopify/Product/1"
      },
      "productVariants": [
        {
          "id": "gid://shopify/ProductVariant/1",
          "media": {
            "edges": []
          }
        },
        {
          "id": "gid://shopify/ProductVariant/2",
          "media": {
            "edges": []
          }
        }
      ],
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 42,
      "actualQueryCost": 14,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 986,
        "restoreRate": 50.0
      }
    }
  }
}
```

***

## Next steps

* Learn how to [manage product media](https://shopify.dev/docs/apps/build/online-store/product-media) by using the GraphQL Admin API.
* Use Liquid to [add product media](https://shopify.dev/docs/storefronts/themes/product-merchandising/media/support-media) to a store's theme.

***

* [Requirements](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#requirements)
* [Step 1: Query a product and display its variants](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-1-query-a-product-and-display-its-variants)
* [Step 2: Create a product and associate media to its variant](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-2-create-a-product-and-associate-media-to-its-variant)
* [Step 3: Attach media to an existing product variant](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-3-attach-media-to-an-existing-product-variant)
* [Step 4: Remove media from a variant](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#step-4-remove-media-from-a-variant)
* [Next steps](https://shopify.dev/docs/apps/build/online-store/product-variant-media.md#next-steps)