--- title: fileUpdate - GraphQL Admin description: |- Updates properties, content, and metadata associated with an existing file asset that has already been uploaded to Shopify. Use the `fileUpdate` mutation to modify various aspects of files already stored in your store. Files can be updated individually or in batches. The `fileUpdate` mutation supports updating multiple file properties: - **Alt text**: Update accessibility descriptions for images and other media. - **File content**: Replace image or generic file content while maintaining the same URL. - **Filename**: Modify file names (extension must match the original). - **Product references**: Add or remove associations between files and products. Removing file-product associations deletes the file from the product's media gallery and clears the image from any product variants that were using it. The mutation handles different file types with specific capabilities: - **Images**: Update preview images, original source, filename, and alt text. - **Generic files**: Update original source, filename, and alt text. - **Videos and 3D models**: Update alt text and product references. > Note: > Files must be in `ready` state before they can be updated. The mutation includes file locking to prevent > conflicts during updates. You can't simultaneously update both `originalSource` and `previewImageSource`. After updating files, you can use related mutations for additional file management: - [`fileCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileCreate): Create new file assets from external URLs or staged uploads. - [`fileDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileDelete): Remove files from your store when they are no longer needed. Learn how to manage [product media and file assets](https://shopify.dev/docs/apps/build/online-store/product-media) in your app. api_version: 2025-10 api_name: admin type: mutation api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileupdate md: https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileupdate.md --- # file​Update mutation Requires `write_files` access scope or `write_themes` access scope. Also: Users must have edit files permissions. Updates properties, content, and metadata associated with an existing file asset that has already been uploaded to Shopify. Use the `fileUpdate` mutation to modify various aspects of files already stored in your store. Files can be updated individually or in batches. The `fileUpdate` mutation supports updating multiple file properties: * **Alt text**: Update accessibility descriptions for images and other media. * **File content**: Replace image or generic file content while maintaining the same URL. * **Filename**: Modify file names (extension must match the original). * **Product references**: Add or remove associations between files and products. Removing file-product associations deletes the file from the product's media gallery and clears the image from any product variants that were using it. The mutation handles different file types with specific capabilities: * **Images**: Update preview images, original source, filename, and alt text. * **Generic files**: Update original source, filename, and alt text. * **Videos and 3D models**: Update alt text and product references. *** Note Files must be in `ready` state before they can be updated. The mutation includes file locking to prevent conflicts during updates. You can't simultaneously update both `originalSource` and `previewImageSource`. *** After updating files, you can use related mutations for additional file management: * [`fileCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileCreate): Create new file assets from external URLs or staged uploads. * [`fileDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileDelete): Remove files from your store when they are no longer needed. Learn how to manage [product media and file assets](https://shopify.dev/docs/apps/build/online-store/product-media) in your app. ## Arguments * files [\[File​Update​Input!\]!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/FileUpdateInput) required List of files to be updated. *** ## File​Update​Payload returns * files [\[File!\]](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/File) The list of updated files. * user​Errors [\[Files​User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/FilesUserError) non-null The list of errors that occurred from executing the mutation. *** ## Examples * ### Handle file update errors and validation #### Description This example demonstrates how the \`fileUpdate\` mutation handles various error conditions and validation failures. Common errors include files that don't exist, alt text that exceeds length limits, and invalid source URLs. The response provides detailed error information with specific field paths and error codes using the \[\`userErrors\`]\(https\://shopify.dev/docs/api/admin-graphql/latest/objects/UserError) object to help you identify and resolve issues quickly. #### Query ```graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } } ``` #### Variables ```json { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn'\''t exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] }, }, }); ``` #### Response ```json { "fileUpdate": { "files": [], "userErrors": [ { "field": [ "files" ], "message": "File id [\"gid://shopify/GenericFile/999999\"] does not exist.", "code": "FILE_DOES_NOT_EXIST" } ] } } ``` * ### Update a file's alt text and other metadata #### Description Update a file's alt text and other metadata to improve accessibility. This example demonstrates updating the alt text of an existing \[image file]\(https\://shopify.dev/docs/api/admin-graphql/latest/objects/MediaImage) to provide better context for screen readers and search engines. The response returns the updated file with its new alt text, file status, and creation timestamp. #### Query ```graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus createdAt ... on MediaImage { image { width height } } } userErrors { field message code } } } ``` #### Variables ```json { "files": [ { "id": "gid://shopify/MediaImage/1072273831", "alt": "High-resolution product image showing laptop computer on modern desk with wireless accessories" } ] } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus createdAt ... on MediaImage { image { width height } } } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/MediaImage/1072273831", "alt": "High-resolution product image showing laptop computer on modern desk with wireless accessories" } ] } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus createdAt ... on MediaImage { image { width height } } } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/MediaImage/1072273831", "alt": "High-resolution product image showing laptop computer on modern desk with wireless accessories" } ] }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus createdAt ... on MediaImage { image { width height } } } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/MediaImage/1072273831", "alt": "High-resolution product image showing laptop computer on modern desk with wireless accessories" } ] } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus createdAt ... on MediaImage { image { width height } } } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/MediaImage/1072273831", "alt": "High-resolution product image showing laptop computer on modern desk with wireless accessories" } ] }, }, }); ``` #### Response ```json { "fileUpdate": { "files": [ { "id": "gid://shopify/MediaImage/1072273831", "alt": "High-resolution product image showing laptop computer on modern desk with wireless accessories", "fileStatus": "READY", "createdAt": "2025-06-22T09:19:04Z", "image": { "width": 372, "height": 110 } } ], "userErrors": [] } } ``` * ### Update file content by replacing the source URL #### Description Update the actual content of a file by providing a new source URL while maintaining the same file ID and URL structure. This example shows how to replace an image file's content with a new version from a different URL, useful for updating product photos or correcting image issues. The operation preserves the file's existing metadata and associations while updating the underlying image data. The response includes the \[\`fileStatus\`]\(https\://shopify.dev/docs/api/admin-graphql/latest/enums/FileStatus) which will show as \`READY\` initially and may change to \`PROCESSING\` during the background update job. Learn more about \[managing media for products]\(https\://shopify.dev/docs/apps/build/online-store/product-media) and \[uploading files]\(https\://help.shopify.com/manual/shopify-admin/productivity-tools/file-uploads). #### Query ```graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt } userErrors { field message code } } } ``` #### Variables ```json { "files": [ { "id": "gid://shopify/MediaImage/1072273829", "originalSource": "https://burst.shopifycdn.com/photos/updated-product-photo.jpg" } ] } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/MediaImage/1072273829", "originalSource": "https://burst.shopifycdn.com/photos/updated-product-photo.jpg" } ] } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/MediaImage/1072273829", "originalSource": "https://burst.shopifycdn.com/photos/updated-product-photo.jpg" } ] }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/MediaImage/1072273829", "originalSource": "https://burst.shopifycdn.com/photos/updated-product-photo.jpg" } ] } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/MediaImage/1072273829", "originalSource": "https://burst.shopifycdn.com/photos/updated-product-photo.jpg" } ] }, }, }); ``` #### Response ```json { "fileUpdate": { "files": [ { "id": "gid://shopify/MediaImage/1072273829", "fileStatus": "READY", "alt": "derp", "createdAt": "2025-06-22T09:19:03Z" } ], "userErrors": [] } } ``` * ### Update multiple files with different operations #### Description Perform multiple update operations on different files in a single request. This example demonstrates updating alt text on multiple files simultaneously to improve accessibility across your media library. Batch operations allow you to make multiple changes efficiently and maintain consistent metadata across related files. The response includes individual file updates showing the new alt text and the \[\`fileStatus\`]\(https\://shopify.dev/docs/api/admin-graphql/latest/enums/FileStatus) for each updated file. Learn more about \[managing media for products]\(https\://shopify.dev/docs/apps/build/online-store/product-media) and \[web accessibility]\(https\://help.shopify.com/manual/online-store/images/alt-text). #### Query ```graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on MediaImage { image { width height } } ... on Video { sources { url width height } } } userErrors { field message code } } } ``` #### Variables ```json { "files": [ { "id": "gid://shopify/MediaImage/1072273826", "alt": "Professional product photography showcasing laptop in modern office environment" }, { "id": "gid://shopify/Video/1072273827", "alt": "Product demonstration video showing laptop features and capabilities" } ] } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on MediaImage { image { width height } } ... on Video { sources { url width height } } } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/MediaImage/1072273826", "alt": "Professional product photography showcasing laptop in modern office environment" }, { "id": "gid://shopify/Video/1072273827", "alt": "Product demonstration video showing laptop features and capabilities" } ] } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on MediaImage { image { width height } } ... on Video { sources { url width height } } } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/MediaImage/1072273826", "alt": "Professional product photography showcasing laptop in modern office environment" }, { "id": "gid://shopify/Video/1072273827", "alt": "Product demonstration video showing laptop features and capabilities" } ] }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on MediaImage { image { width height } } ... on Video { sources { url width height } } } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/MediaImage/1072273826", "alt": "Professional product photography showcasing laptop in modern office environment" }, { "id": "gid://shopify/Video/1072273827", "alt": "Product demonstration video showing laptop features and capabilities" } ] } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on MediaImage { image { width height } } ... on Video { sources { url width height } } } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/MediaImage/1072273826", "alt": "Professional product photography showcasing laptop in modern office environment" }, { "id": "gid://shopify/Video/1072273827", "alt": "Product demonstration video showing laptop features and capabilities" } ] }, }, }); ``` #### Response ```json { "fileUpdate": { "files": [ { "id": "gid://shopify/MediaImage/1072273826", "alt": "Professional product photography showcasing laptop in modern office environment", "fileStatus": "READY", "image": { "width": 372, "height": 110 } }, { "id": "gid://shopify/Video/1072273827", "alt": "Product demonstration video showing laptop features and capabilities", "fileStatus": "READY", "sources": [ { "url": "https://cdn.shopify.com/videos/:/vp/some_hash/some_other_hash.m3u8", "width": 1280, "height": 720 }, { "url": "https://cdn.shopify.com/videos/c/vp/some_hash/some_other_hash.HD-720p-4.5Mbps.mp4", "width": 1280, "height": 720 }, { "url": "https://cdn.shopify.com/videos/c/vp/some_hash/some_other_hash.SD-480p-1.5Mbps.mp4", "width": 854, "height": 480 } ] } ], "userErrors": [] } } ``` * ### Update the preview image for a video file #### Description Update the preview image (thumbnail) for a video file to provide a better visual representation in your store. This example shows how to change the preview image of an existing video by providing a new image URL. Shopify will download, validate, process, and optimize your image from the provided URL before using it as the thumbnail. The response includes the updated file information and the \[\`fileStatus\`]\(https\://shopify.dev/docs/api/admin-graphql/latest/enums/FileStatus) for the new preview image. Learn more about \[managing media for products]\(https\://shopify.dev/docs/apps/build/online-store/product-media) and \[uploading files]\(https\://help.shopify.com/manual/shopify-admin/productivity-tools/file-uploads). #### Query ```graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on Video { sources { url width height } } } userErrors { field message code } } } ``` #### Variables ```json { "files": [ { "id": "gid://shopify/Video/1072273828", "previewImageSource": "https://burst.shopifycdn.com/photos/video-thumbnail.jpg" } ] } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on Video { sources { url width height } } } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/Video/1072273828", "previewImageSource": "https://burst.shopifycdn.com/photos/video-thumbnail.jpg" } ] } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on Video { sources { url width height } } } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/Video/1072273828", "previewImageSource": "https://burst.shopifycdn.com/photos/video-thumbnail.jpg" } ] }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on Video { sources { url width height } } } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/Video/1072273828", "previewImageSource": "https://burst.shopifycdn.com/photos/video-thumbnail.jpg" } ] } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus ... on Video { sources { url width height } } } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/Video/1072273828", "previewImageSource": "https://burst.shopifycdn.com/photos/video-thumbnail.jpg" } ] }, }, }); ``` #### Response ```json { "fileUpdate": { "files": [ { "id": "gid://shopify/Video/1072273828", "alt": "", "fileStatus": "READY", "sources": [ { "url": "https://cdn.shopify.com/videos/:/vp/some_hash/some_other_hash.m3u8", "width": 1280, "height": 720 }, { "url": "https://cdn.shopify.com/videos/c/vp/some_hash/some_other_hash.HD-720p-4.5Mbps.mp4", "width": 1280, "height": 720 }, { "url": "https://cdn.shopify.com/videos/c/vp/some_hash/some_other_hash.SD-480p-1.5Mbps.mp4", "width": 854, "height": 480 } ] } ], "userErrors": [] } } ``` * ### Update video file metadata #### Description Update a video file's metadata such as alt text to improve accessibility and provide better context for users. This example demonstrates updating the alt text of a video file to describe its content for screen readers and search engines. The response returns the updated \[video]\(https\://shopify.dev/docs/api/admin-graphql/latest/objects/Video) with its new metadata, \[file status]\(https\://shopify.dev/docs/api/admin-graphql/latest/enums/FileStatus), and video source information. Learn more about \[managing media for products]\(https\://shopify.dev/docs/apps/build/online-store/product-media) and \[web accessibility]\(https\://help.shopify.com/manual/online-store/images/alt-text). #### Query ```graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt ... on Video { sources { url width height } } } userErrors { field message code } } } ``` #### Variables ```json { "files": [ { "id": "gid://shopify/Video/1072273830", "alt": "Product demonstration video showing step-by-step assembly instructions and safety guidelines" } ] } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt ... on Video { sources { url width height } } } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/Video/1072273830", "alt": "Product demonstration video showing step-by-step assembly instructions and safety guidelines" } ] } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt ... on Video { sources { url width height } } } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/Video/1072273830", "alt": "Product demonstration video showing step-by-step assembly instructions and safety guidelines" } ] }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt ... on Video { sources { url width height } } } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/Video/1072273830", "alt": "Product demonstration video showing step-by-step assembly instructions and safety guidelines" } ] } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id fileStatus alt createdAt ... on Video { sources { url width height } } } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/Video/1072273830", "alt": "Product demonstration video showing step-by-step assembly instructions and safety guidelines" } ] }, }, }); ``` #### Response ```json { "fileUpdate": { "files": [ { "id": "gid://shopify/Video/1072273830", "fileStatus": "READY", "alt": "Product demonstration video showing step-by-step assembly instructions and safety guidelines", "createdAt": "2025-06-22T09:19:03Z", "sources": [ { "url": "https://cdn.shopify.com/videos/:/vp/some_hash/some_other_hash.m3u8", "width": 1280, "height": 720 }, { "url": "https://cdn.shopify.com/videos/c/vp/some_hash/some_other_hash.HD-720p-4.5Mbps.mp4", "width": 1280, "height": 720 }, { "url": "https://cdn.shopify.com/videos/c/vp/some_hash/some_other_hash.SD-480p-1.5Mbps.mp4", "width": 854, "height": 480 } ] } ], "userErrors": [] } } ``` * ### fileUpdate reference [Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20fileUpdate\(%24files%3A%20%5BFileUpdateInput!%5D!\)%20%7B%0A%20%20fileUpdate\(files%3A%20%24files\)%20%7B%0A%20%20%20%20files%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%20%20alt%0A%20%20%20%20%20%20fileStatus%0A%20%20%20%20%7D%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%20%20code%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22files%22%3A%20%5B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22id%22%3A%20%22gid%3A%2F%2Fshopify%2FGenericFile%2F999999%22%2C%0A%20%20%20%20%20%20%22alt%22%3A%20%22File%20that%20doesn't%20exist%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22id%22%3A%20%22gid%3A%2F%2Fshopify%2FGenericFile%2F1072273825%22%2C%0A%20%20%20%20%20%20%22alt%22%3A%20%22aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa%22%0A%20%20%20%20%7D%0A%20%20%5D%0A%7D) ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] }, }, ); const json = await response.json(); return json.data; } ``` ##### GQL ``` mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } } ``` ##### cURL ``` curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }", "variables": { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn'\''t exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] } }' ``` ##### React Router ``` import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }`, { variables: { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] }, }, ); const json = await response.json(); return json.data; } ``` ##### Node.js ``` const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "query": `mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } }`, "variables": { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] }, }, }); ``` ##### Ruby ``` session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~QUERY mutation fileUpdate($files: [FileUpdateInput!]!) { fileUpdate(files: $files) { files { id alt fileStatus } userErrors { field message code } } } QUERY variables = { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] } response = client.query(query: query, variables: variables) ``` ## Input variables JSON ```json { "files": [ { "id": "gid://shopify/GenericFile/999999", "alt": "File that doesn't exist" }, { "id": "gid://shopify/GenericFile/1072273825", "alt": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ] } ``` ## Response JSON ```json { "fileUpdate": { "files": [], "userErrors": [ { "field": [ "files" ], "message": "File id [\"gid://shopify/GenericFile/999999\"] does not exist.", "code": "FILE_DOES_NOT_EXIST" } ] } } ```