Manage variant media with the GraphQL Admin API

As of version 2020-10, 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, variant, and media object, and attach a media object to a variant in a single step. You can also associate the product's media to its variants.

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



To use the variant media GraphQL mutations, your app needs to request the following access scopes for a Shopify store:

  • read_products: Allows your app to read products.
  • write_products: Allows your app to write mutations on products.


  • Although the media input accepts an array, as of version 2020-10, the input is limited to one media object, which must be an image.
  • The mediaSrc attribute is currently non-operational on productVariantCreate.

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 /admin/api/2020-10/graphql.json

Create a product and associate media to its variant

When you create a new product using the productCreate mutation, you can include the mediaSrc attribute to specify the URL of the media to associate with the variant. This field match 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 /admin/api/2020-10/graphql.json