Manage media for products

• Your app can make authenticated requests to the GraphQL Admin API and Storefront API.
• Your app has the read_products and write_products access scopes. Learn how to configure your access scopes using Shopify CLI.
• You're performing actions on product media that are supported by the API you're working with:
  • GraphQL Admin API: Supports uploading media, adding media to a product, retrieving media, and deleting media
  • Storefront API: Only supports retrieving media
• You're working within the constraints of the plan-based limits for product media. There's a limit to the number of Shopify-hosted videos and 3D models that a store can have. The limit depends on the Shopify plan that the store is on:
  • Basic Shopify: 250
  • Shopify: 1,000
  • Advanced Shopify: 5,000
  • Shopify Plus: Contact Plus Support

A product can have different media types:

• 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 10 minutes 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 GLB or USDZ format. The asset can be retrieved in GLB and USDZ formats. The file size must be 500 MB or smaller.

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.

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 URL where you can upload the media asset
• resourceUrl: The URL that you pass to productCreateMedia in the originalSource field after the asset has been uploaded

The mutation accepts an input of type stagedUploadInput, which has the following fields:

The following example uses the stagedUploadsCreate mutation to generate the upload values required to upload an MP4 video and a 3D model.

After generating the parameters and URL for an upload, you need to upload the asset by using a POST or PUT request. The request is formatted differently depending on the media type and the HTTP method that you're using.

Use a multipart form, and include all parameters as form inputs in the request body:

Use a multipart form, and include all parameters as form inputs in the request body:

Use a multipart form, and include all parameters as form inputs in the request body:

Include the parameters as request headers. Additional parameters are already included in the URL:

You can add new media to a product by using the productCreateMedia mutation. The mutation takes two arguments:

• productId: The ID of the product that you're adding media to.
• media: An array of CreateMediaInput objects.

For each CreateMediaInput object, include the following fields:

The following example adds a Shopify-hosted video to a product:

You can retrieve a product's media of all types by using the media connection on the Product type. The connection returns nodes that implement the Media interface.

The media connection includes the mediaContentType field, which you can use to check the media type of each node. Because each media type can return different fields, you can specify the return fields for each type by using fragments:

With the Storefront API, use the media field on the Product type to query for a product's media. Use a fragment to specify the fields that you want to return for each possible media type.

When you add a piece of media to a product, Shopify needs to process the media before it can be displayed.

The Media interface includes the status field, which you can use to check whether the media has been processed. The status field can return different values.

You can use the productUpdateMedia mutation to update a piece of media associated with a product. As part of the mutation input, include the following arguments:

• productId: The ID of the product that the media belongs to.
• media: An array of media changes to apply.

You can change a media item's alt text or preview image URL. Include the media's ID to identify the media you want to update. Identify the media to update by its ID. For example, the GraphQL variable below updates the alt text of the MediaImage with ID gid://shopify/MediaImage/42729528:

The following example shows how to use the productUpdateMedia mutation to update the alt text of a piece of media. The example uses a JSON variable to provide the media changes, and a fragment to select the return fields based on the media type.

You can reorder a product’s media by using the productReorderMedia mutation. The mutation accepts two arguments:

• id: The ID of the product whose media you’re reordering.

• moves: An array of tuples consisting of a media object’s ID and its new position in the list. For example, the following array would move the media objects to the front of the product’s media list:

The following example adjusts the order of a products first three media assets:

You can use the returned ID for the job to poll for when the reordering job is complete.

To delete media assets from a product, use the productDeleteMedia mutation. The mutation accepts two arguments:

• productId: The ID of the product whose media you’re deleting.
• mediaIds: An array of IDs for the media that you’re deleting.

The following example deletes two media assets from a product:

• Manage media objects on product variants with the GraphQL Admin API.
• Use Liquid to add product media to a store's theme.