Choose a version:

fileCreate

mutation

Requires write_files access scope, write_themes access scope or write_images access scope. Also: Users must have create files permissions.

Creates file assets for a store from external URLs or files that were previously uploaded using the stagedUploadsCreate mutation.

Use the fileCreate mutation to add various types of media and documents to your store. These files are added to the Files page in the Shopify admin and can be referenced by other resources in your store.

The fileCreate mutation supports multiple file types:

Images: Product photos, variant images, and general store imagery
Videos: Shopify-hosted videos for product demonstrations and marketing
External videos: YouTube and Vimeo videos for enhanced product experiences
3D models: Interactive 3D representations of products
Generic files: PDFs, documents, and other file types for store resources

The mutation handles duplicate filenames using configurable resolution modes that automatically append UUIDs, replace existing files, or raise errors when conflicts occur.

Note

Files are processed asynchronously. Check the fileStatus field to monitor processing completion. The maximum number of files that can be created in a single batch is 250.

After creating files, you can make subsequent updates using the following mutations:

fileUpdate: Update file properties such as alt text or replace file contents while preserving the same URL.
fileDelete: Remove files from your store when they are no longer needed.

To list all files in your store, use the files query.

Learn how to manage product media and file assets in your app.

Arguments

Anchor to filesfiles •[FileCreateInput!]! required: List of new files to be created.

Was this section helpful?

Anchor to FileCreatePayload returnsFileCreatePayload returns

Anchor to filesfiles •[File!]: The newly created files.
Anchor to userErrorsuserErrors •[FilesUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Create a file using a staged upload URL
Create mixed media files with custom filenames
Create product documentation files from external URLs
Create product image files from external URLs
Handle file creation errors and validation
fileCreate reference

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation fileCreate($files: [FileCreateInput!]!) {

fileCreate(files: $files) {

files {

fileStatus

alt

createdAt

... on MediaImage {

image {

width

height

}

userErrors {

field

message

}

}`,

{

variables: {

"files": [

{

"alt": "Product showcase image from staged upload",

"contentType": "IMAGE",

"originalSource": "https://snowdevil.myshopify.com/admin/tmp/files/staged-image-upload-123.jpg"

}

]

);

const data = await response.json();

mutation fileCreate($files: [FileCreateInput!]!) {
  fileCreate(files: $files) {
    files {
      id
      fileStatus
      alt
      createdAt
      ... on MediaImage {
        image {
          width
          height
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation fileCreate($files: [FileCreateInput!]!) { fileCreate(files: $files) { files { id fileStatus alt createdAt ... on MediaImage { image { width height } } } userErrors { field message } } }",
 "variables": {
    "files": [
      {
        "alt": "Product showcase image from staged upload",
        "contentType": "IMAGE",
        "originalSource": "https://snowdevil.myshopify.com/admin/tmp/files/staged-image-upload-123.jpg"
      }
    ]
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation fileCreate($files: [FileCreateInput!]!) {
    fileCreate(files: $files) {
      files {
        id
        fileStatus
        alt
        createdAt
        ... on MediaImage {
          image {
            width
            height
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
      "files": [
        {
          "alt": "Product showcase image from staged upload",
          "contentType": "IMAGE",
          "originalSource": "https://snowdevil.myshopify.com/admin/tmp/files/staged-image-upload-123.jpg"
        }
      ]
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation fileCreate($files: [FileCreateInput!]!) {
      fileCreate(files: $files) {
        files {
          id
          fileStatus
          alt
          createdAt
          ... on MediaImage {
            image {
              width
              height
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
      "files": [
        {
          "alt": "Product showcase image from staged upload",
          "contentType": "IMAGE",
          "originalSource": "https://snowdevil.myshopify.com/admin/tmp/files/staged-image-upload-123.jpg"
        }
      ]
    },
  },
});

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 fileCreate($files: [FileCreateInput!]!) {
    fileCreate(files: $files) {
      files {
        id
        fileStatus
        alt
        createdAt
        ... on MediaImage {
          image {
            width
            height
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "files": [{"alt"=>"Product showcase image from staged upload", "contentType"=>"IMAGE", "originalSource"=>"https://snowdevil.myshopify.com/admin/tmp/files/staged-image-upload-123.jpg"}]
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"files": [

{

"alt": "Product showcase image from staged upload",

"contentType": "IMAGE",

"originalSource": "https://snowdevil.myshopify.com/admin/tmp/files/staged-image-upload-123.jpg"

}

]

}

Response

JSON

{

"fileCreate": {

"files": [

{

"id": "gid://shopify/MediaImage/1072273436",

"fileStatus": "READY",

"alt": "Product showcase image from staged upload",

"createdAt": "2025-06-21T03:47:03Z",

"image": {

"width": 372,

"height": 110

}

"userErrors": []

}