Manage media for products and collections

Use the GraphQL Admin API to manage media for products and collections. The API supports images, Shopify-hosted videos, external videos (YouTube and Vimeo), and 3D models.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the latest version of the GraphQL Admin API or higher.
• Your app has the read_products, write_products, and write_files access scopes. Learn how to configure your access scopes using Shopify CLI.
• You've created products to associate media with. If you need to create products first, refer to Add product data.

Anchor to How it worksHow it works

The GraphQL Admin API manages files independently from products using a unified file system. Upload a file once to Shopify's CDN using fileCreate or stagedUploadsCreate, get a unique file ID, then reference that ID from multiple products, variants, collections, or themes. Updates to the file propagate everywhere it's used.

Files are processed asynchronously. You poll the fileStatus field until it's READY, then associate the file with products using the file ID. This separation allows file reuse across resources and prevents duplicate uploads. For example, one product image can be referenced by multiple products without uploading it multiple times.

Anchor to Supported media typesSupported media types

Anchor to Step 1: Upload files to ShopifyStep 1: Upload files to Shopify

Before you can display media to customers, files must be hosted on Shopify's CDN. Shopify processes files asynchronously, generating multiple sizes for images, transcoding videos to multiple resolutions, and optimizing 3D models. Files are then served globally through a fast CDN.

The GraphQL Admin API provides two approaches for uploading files:

Anchor to Option A: Upload from a URL with ,[object Object]Option A: Upload from a URL with fileCreate

Use fileCreate when your files are already accessible at a public URL. This is the simplest approach: you provide a URL and Shopify handles downloading, processing, and storing the file.

The following example uploads an image from an external URL:

Anchor to Option B: Upload directly with ,[object Object]Option B: Upload directly with stagedUploadsCreate

Use stagedUploadsCreate when you need more control over the upload process. This two-step approach is recommended for:

• Large files: Videos, 3D models, and high-resolution images benefit from direct uploads.
• Files on your server: Files that aren't accessible via public URL.
• Unreliable networks: Direct uploads handle interruptions more gracefully.
• Bulk imports: Uploading many files efficiently.

Anchor to 1. Generate upload credentials1. Generate upload credentials

Generate secure upload credentials for your files. You must specify the fileSize for videos and 3D models:

Anchor to 2. Upload the file2. Upload the file

Upload the file to the url using the provided parameters. The request format differs by media type.

Videos and 3D models use a POST request with multipart form data:

Images use a PUT request with parameters as headers:

Anchor to 3. Register the uploaded file3. Register the uploaded file

After uploading, register the file with Shopify using fileCreate. Use the resourceUrl from the staged upload response as the originalSource:

Anchor to Step 2: Poll for file readinessStep 2: Poll for file readiness

Regardless of which upload method you use, files are processed asynchronously. Poll the fileStatus field until it becomes READY before associating the file with products:

• UPLOADED: File has been received by Shopify's servers.
• PROCESSING: File is being processed (resized, transcoded, and so on).
• READY: File is ready to associate with products.
• FAILED: Processing failed. Check error details.

Anchor to Step 3: Add media to productsStep 3: Add media to products

After a file's status is READY, you can associate it with products to display the media to customers. This association determines which media appears on product pages, in collection listings, and across sales channels.

Use productSet, productCreate, or productUpdate with the media field. Reference the file by its ID in the originalSource field.

Anchor to Step 4: Add media to product variantsStep 4: Add media to product variants

You can add media to variants when creating products by using the mediaSrc field in productCreate. The mediaSrc value must match one of the media originalSource fields on the product.

The following example shows how to add media when creating a product with variants:

Anchor to Step 5: Add images to collectionsStep 5: Add images to collections

Collection images appear in collection listings, navigation menus, and promotional banners. Unlike products, collections use image URLs directly instead of file ID references.

To add images to collections, use collectionCreate or collectionUpdate with image URLs. You can use Shopify CDN URLs from uploaded files or external URLs from your own hosting.

Anchor to Option A: Use Shopify CDN filesOption A: Use Shopify CDN files

To add a file from Shopify's CDN to a collection, first upload it with fileCreate, get the CDN URL from the file, then use that URL in the collection mutation.

First, query the file to get its CDN URL:

Then create the collection with the image URL:

Anchor to Option B: Use external image URLsOption B: Use external image URLs

You can also provide external URLs directly without uploading to Shopify. This is useful when you host images on your own CDN or need to update images frequently without re-uploading.

Anchor to Step 6: Update and reorder mediaStep 6: Update and reorder media

After adding media to products, you might need to update which products reference a file or change the display order.

Anchor to Update file associationsUpdate file associations

The unified file system's key advantage is file reuse. When you have a logo, brand image, or shared product shot, you can use the same file across multiple products without uploading duplicates. Use fileUpdate to manage which products reference a file.

The following example shows how to move a file from one product to another:

Anchor to Reorder product mediaReorder product media

The first media item in a product typically serves as the primary image in collection pages, search results, and product thumbnails. Use productReorderMedia to change media order without deleting and re-adding items.

Anchor to Update collection imagesUpdate collection images

To update a collection's image, use collectionUpdate with the new image URL:

Anchor to Step 7: Delete filesStep 7: Delete files

Use fileDelete to permanently remove files from your shop. This is useful for removing discontinued product images, cleaning up test files, or freeing storage space.

Anchor to Next stepsNext steps

• Learn how to add product data.
• Learn how to update product data.
• Explore the fileCreate mutation in the GraphQL Admin API reference.