Manage product media with the GraphQL Admin API

Versions 2020-01 and higher

You can use the GraphQL Admin API to manage the various types of media associated with merchants' products. You can also use the Storefront API to retrieve a product's media and display it on a custom storefront. This guide explains the different types of product media, and how to use Shopify's API to work with them.

Only the GraphQL Admin API and Storefront APIs support working with all types of product media. The REST Admin API supports only product images.

Required access

read_products, write_products access scopes.

Product media types

A product can have the following media types:

GraphQL type Description
MediaImage An image in one of the following formats: PNG, GIF, or JPG. The maximum image size is 4472 x 4472 px, or 20 megapixels. For square images, 2048 x 2048 px looks best.
Video An MP4 video that's hosted by Shopify. The video runtime must be 1 minute or shorter. The maximum file size is 1 GB.
ExternalVideo A video that's hosted on YouTube or Vimeo, specified by its embed URL.
Model3d A 3D model provided in the GLB format. The asset can be retrieved in GLB and USDZ formats. The file size must be 15 MB or smaller.

Media actions supported by GraphQL

The GraphQL Admin API and the Storefront API both support working with all media types. The actions that you can perform on product media depend on which API you're using:

API Upload media Add media to a product Retrieve media Delete media
GraphQL Admin API
Storefront API - - -

Uploading media to Shopify

Before you add a piece of media to a product, you can upload it and host it on Shopify. There are two parts to uploading an asset to Shopify:

  1. Generate the upload URL and parameters
  2. Upload the asset

The number of media assets that a shop can upload varies, depending on the shop's Shopify plan. To learn more, see Plan-based limits for product media.

Generate the upload URL and parameters

You can use the stagedUploadsCreate mutation to generate the values that you need to authenticate multiple uploads. The mutation returns the stagedTargets array. Each staged target has the following properties:

  • params — The parameters that you use to authenticate an upload request
  • url — The signed URL whe