Choose a version:

themeFilesUpsert

mutation

Requires The user needs write_themes and an exemption from Shopify to modify theme files. If you think that your app is eligible for an exemption and should have access to this API, then you can submit an exception request.

Creates or updates theme files in an online store theme. This mutation allows batch operations on multiple theme files, either creating new files or overwriting existing ones with the same filename.

Note

You can process a maximum of 50 files in a single request.

Each file requires a filename and body content. The body must specify a type with the corresponding value. The mutation returns a job field for tracking asynchronous operations and an upsertedThemeFiles field with details about the processed files.

Anchor to Arguments

Arguments

Anchor to filesfiles

•[OnlineStoreThemeFilesUpsertFileInput!]!

required

The files to update.

Anchor to themeIdthemeId

•ID!

required

The theme to update.

Was this section helpful?

Anchor to ThemeFilesUpsertPayload returnsThemeFilesUpsertPayload returns

Anchor to jobjob •Job: The theme files write job triggered by the mutation.
Anchor to upsertedThemeFilesupsertedThemeFiles •[OnlineStoreThemeFileOperationResult!]: The resulting theme files.
Anchor to userErrorsuserErrors •[OnlineStoreThemeFilesUserErrors!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Create or update a theme file

Query

mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
  themeFilesUpsert(files: $files, themeId: $themeId) {
    upsertedThemeFiles {
      filename
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) { themeFilesUpsert(files: $files, themeId: $themeId) { upsertedThemeFiles { filename } userErrors { field message } } }",
 "variables": {
    "themeId": "gid://shopify/OnlineStoreTheme/529529152",
    "files": [
      {
        "filename": "templates/index.json",
        "body": {
          "type": "TEXT",
          "value": "{ \"sections\": {}, \"order\": [] }"
        }
      }
    ]
  }
}'

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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
    themeFilesUpsert(files: $files, themeId: $themeId) {
      upsertedThemeFiles {
        filename
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            }
        ]
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
    themeFilesUpsert(files: $files, themeId: $themeId) {
      upsertedThemeFiles {
        filename
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
      themeFilesUpsert(files: $files, themeId: $themeId) {
        upsertedThemeFiles {
          filename
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            }
        ]
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
  themeFilesUpsert(files: $files, themeId: $themeId) {
    upsertedThemeFiles {
      filename
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    }
  ]
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
        themeFilesUpsert(files: $files, themeId: $themeId) {
          upsertedThemeFiles {
            filename
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            }
        ]
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "themeFilesUpsert": {
    "upsertedThemeFiles": [
      {
        "filename": "templates/index.json"
      }
    ],
    "userErrors": []
  }
}

Create or update theme files in bulk

Query

mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
  themeFilesUpsert(files: $files, themeId: $themeId) {
    upsertedThemeFiles {
      filename
    }
    job {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    },
    {
      "filename": "assets/custom-content.txt",
      "body": {
        "type": "BASE64",
        "value": "Y3VzdG9tIGNvbnRlbnQ="
      }
    },
    {
      "filename": "assets/large-dog-image.jpg",
      "body": {
        "type": "URL",
        "value": "https://www.example.com/large-dog-image.jpg"
      }
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) { themeFilesUpsert(files: $files, themeId: $themeId) { upsertedThemeFiles { filename } job { id } userErrors { field message } } }",
 "variables": {
    "themeId": "gid://shopify/OnlineStoreTheme/529529152",
    "files": [
      {
        "filename": "templates/index.json",
        "body": {
          "type": "TEXT",
          "value": "{ \"sections\": {}, \"order\": [] }"
        }
      },
      {
        "filename": "assets/custom-content.txt",
        "body": {
          "type": "BASE64",
          "value": "Y3VzdG9tIGNvbnRlbnQ="
        }
      },
      {
        "filename": "assets/large-dog-image.jpg",
        "body": {
          "type": "URL",
          "value": "https://www.example.com/large-dog-image.jpg"
        }
      }
    ]
  }
}'

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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
    themeFilesUpsert(files: $files, themeId: $themeId) {
      upsertedThemeFiles {
        filename
      }
      job {
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            },
            {
                "filename": "assets/custom-content.txt",
                "body": {
                    "type": "BASE64",
                    "value": "Y3VzdG9tIGNvbnRlbnQ="
                }
            },
            {
                "filename": "assets/large-dog-image.jpg",
                "body": {
                    "type": "URL",
                    "value": "https://www.example.com/large-dog-image.jpg"
                }
            }
        ]
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
    themeFilesUpsert(files: $files, themeId: $themeId) {
      upsertedThemeFiles {
        filename
      }
      job {
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    },
    {
      "filename": "assets/custom-content.txt",
      "body": {
        "type": "BASE64",
        "value": "Y3VzdG9tIGNvbnRlbnQ="
      }
    },
    {
      "filename": "assets/large-dog-image.jpg",
      "body": {
        "type": "URL",
        "value": "https://www.example.com/large-dog-image.jpg"
      }
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
      themeFilesUpsert(files: $files, themeId: $themeId) {
        upsertedThemeFiles {
          filename
        }
        job {
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            },
            {
                "filename": "assets/custom-content.txt",
                "body": {
                    "type": "BASE64",
                    "value": "Y3VzdG9tIGNvbnRlbnQ="
                }
            },
            {
                "filename": "assets/large-dog-image.jpg",
                "body": {
                    "type": "URL",
                    "value": "https://www.example.com/large-dog-image.jpg"
                }
            }
        ]
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
  themeFilesUpsert(files: $files, themeId: $themeId) {
    upsertedThemeFiles {
      filename
    }
    job {
      id
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    },
    {
      "filename": "assets/custom-content.txt",
      "body": {
        "type": "BASE64",
        "value": "Y3VzdG9tIGNvbnRlbnQ="
      }
    },
    {
      "filename": "assets/large-dog-image.jpg",
      "body": {
        "type": "URL",
        "value": "https://www.example.com/large-dog-image.jpg"
      }
    }
  ]
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
        themeFilesUpsert(files: $files, themeId: $themeId) {
          upsertedThemeFiles {
            filename
          }
          job {
            id
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            },
            {
                "filename": "assets/custom-content.txt",
                "body": {
                    "type": "BASE64",
                    "value": "Y3VzdG9tIGNvbnRlbnQ="
                }
            },
            {
                "filename": "assets/large-dog-image.jpg",
                "body": {
                    "type": "URL",
                    "value": "https://www.example.com/large-dog-image.jpg"
                }
            }
        ]
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "themeFilesUpsert": {
    "upsertedThemeFiles": [
      {
        "filename": "templates/index.json"
      },
      {
        "filename": "assets/custom-content.txt"
      }
    ],
    "job": {
      "id": "gid://shopify/Job/ae8d210d-90e0-4912-96d0-96d45c5e8fbb"
    },
    "userErrors": []
  }
}

themeFilesUpsert reference

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

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

const response = await admin.graphql(

`#graphql

mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {

themeFilesUpsert(files: $files, themeId: $themeId) {

upsertedThemeFiles {

filename

}

userErrors {

field

message

}

}`,

{

variables: {

"themeId": "gid://shopify/OnlineStoreTheme/529529152",

"files": [

{

"filename": "templates/index.json",

"body": {

"type": "TEXT",

"value": "{ \"sections\": {}, \"order\": [] }"

}

]

);

const json = await response.json();

return json.data;

}

GQL

mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
  themeFilesUpsert(files: $files, themeId: $themeId) {
    upsertedThemeFiles {
      filename
    }
    userErrors {
      field
      message
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) { themeFilesUpsert(files: $files, themeId: $themeId) { upsertedThemeFiles { filename } userErrors { field message } } }",
 "variables": {
    "themeId": "gid://shopify/OnlineStoreTheme/529529152",
    "files": [
      {
        "filename": "templates/index.json",
        "body": {
          "type": "TEXT",
          "value": "{ \"sections\": {}, \"order\": [] }"
        }
      }
    ]
  }
}'

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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
    themeFilesUpsert(files: $files, themeId: $themeId) {
      upsertedThemeFiles {
        filename
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            }
        ]
    },
  },
  );
  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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
      themeFilesUpsert(files: $files, themeId: $themeId) {
        upsertedThemeFiles {
          filename
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            }
        ]
    },
  },
});

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 themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
    themeFilesUpsert(files: $files, themeId: $themeId) {
      upsertedThemeFiles {
        filename
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    }
  ]
}

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

Shopify CLI

shopify app execute \
--query \
'mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
  themeFilesUpsert(files: $files, themeId: $themeId) {
    upsertedThemeFiles {
      filename
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "filename": "templates/index.json",
      "body": {
        "type": "TEXT",
        "value": "{ \"sections\": {}, \"order\": [] }"
      }
    }
  ]
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation themeFilesUpsert($files: [OnlineStoreThemeFilesUpsertFileInput!]!, $themeId: ID!) {
        themeFilesUpsert(files: $files, themeId: $themeId) {
          upsertedThemeFiles {
            filename
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "themeId": "gid://shopify/OnlineStoreTheme/529529152",
        "files": [
            {
                "filename": "templates/index.json",
                "body": {
                    "type": "TEXT",
                    "value": "{ \"sections\": {}, \"order\": [] }"
                }
            }
        ]
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"themeId": "gid://shopify/OnlineStoreTheme/529529152",

"files": [

{

"filename": "templates/index.json",

"body": {

"type": "TEXT",

"value": "{ \"sections\": {}, \"order\": [] }"

}

]

}

Response

JSON

{

"themeFilesUpsert": {

"upsertedThemeFiles": [

{

"filename": "templates/index.json"

}

"userErrors": []

}