Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Theme

Requires themes access scope.

A theme controls the look and feel of a Shopify online store.

A store can have a maximum of 20 themes, one of which is the published theme that customers see when they visit the online store. Customers can't see unpublished themes. When you publish a theme, the previously published theme becomes unpublished.

To modify theme files after they're uploaded, use the Asset resource. To learn how to create your own theme, refer to Building themes

Was this section helpful?
#

Endpoints

Anchor to

The Theme resource

Anchor to

Properties

created_at
read-only
->
createdAt

The date and time when the theme was created. (format: 2014-04-25T16:15:47-04:00)

id
read-only
->
id

The unique numeric identifier for the theme.

name
->
name

The name of the theme.

previewable
read-only
deprecated

Whether the theme can currently be previewed.

processing
read-only
->
processing

Whether files are still being copied into place for this theme.

role
->
role

Specifies how the theme is being used within the shop. Valid values:

Show role properties
  • main: The theme is published. Customers see it when they visit the online store.
  • unpublished: The theme is unpublished. Customers can't see it.
  • demo: The theme is installed on the store as a demo. The theme can't be published until the merchant buys the full version.
  • development: The theme is used for development. The theme can't be published, and is temporary.
src

Specifies a public URL where Shopify can access the theme code.

theme_store_id
read-only
->
themeStoreId

A unique identifier applied to Shopify-made themes that are installed from the Shopify Theme Store Theme Store. Not all themes available in the Theme Store are developed by Shopify. Returns null if the store's theme isn't made by Shopify, or if it wasn't installed from the Theme Store.

updated_at
read-only
->
updatedAt

The date and time of when the theme was last updated. (format: 2014-04-25T16:15:47-04:00)

Was this section helpful?
{}

The Theme resource

{
"created_at": "2012-08-24T14:01:47-04:00",
"id": 828155753,
"name": "Comfort",
"previewable": true,
"processing": true,
"role": "main",
"src": "http://themes.shopify.com/theme.zip",
"theme_store_id": 775,
"updated_at": "2012-08-24T14:01:47-04:00"
}

Anchor to POST request, Creates a theme
post
Creates a theme

themeCreate

Creates a theme by providing the public URL of a ZIP file that contains the theme.

A new theme is always unpublished by default. To publish a theme when you create it, include "role": "main" in the POST request. The theme will be published only after all of its files have been extracted and stored by Shopify, which might take a couple of minutes.

Anchor to Parameters of Creates a themeParameters

api_version
string
required
Was this section helpful?

Anchor to post-themes-examplesExamples

Create a theme that has a custom name and is published

Request body
theme
Theme resource
Show theme properties
theme.name:"Lemongrass"

The name of the theme.

theme.src:"http://themes.shopify.com/theme.zip"

Specifies a public URL where Shopify can access the theme code.

theme.role:"main"

Specifies how the theme is being used within the shop. Valid values:

Show role properties
  • main: The theme is published. Customers see it when they visit the online store.
  • unpublished: The theme is unpublished. Customers can't see it.
  • demo: The theme is installed on the store as a demo. The theme can't be published until the merchant buys the full version.
  • development: The theme is used for development. The theme can't be published, and is temporary.

Creating a theme without a name fails and returns an error

Was this section helpful?
post

/admin/api/2025-07/themes.json

curl -d '{"theme":{"name":"Lemongrass","src":"http://themes.shopify.com/theme.zip","role":"main"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/themes.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 201 Created
{
"theme": {
"id": 1049083723,
"name": "Lemongrass",
"created_at": "2025-07-01T14:04:24-04:00",
"updated_at": "2025-07-01T14:04:24-04:00",
"role": "unpublished",
"theme_store_id": null,
"previewable": false,
"processing": true,
"admin_graphql_api_id": "gid://shopify/Theme/1049083723"
}
}

Anchor to GET request, Retrieves a list of themes
get
Retrieves a list of themes

themes

Retrieves a list of themes.

Anchor to Parameters of Retrieves a list of themesParameters

api_version
string
required
fields

Show only certain fields, specified by a comma-separated list of field names.

Was this section helpful?

Anchor to get-themes-examplesExamples

Retrieve a list of themes

Was this section helpful?
get

/admin/api/2025-07/themes.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/themes.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"themes": [
{
"id": 828155753,
"name": "Comfort",
"created_at": "2025-07-01T14:03:22-04:00",
"updated_at": "2025-07-01T14:03:22-04:00",
"role": "main",
"theme_store_id": null,
"previewable": true,
"processing": false,
"admin_graphql_api_id": "gid://shopify/Theme/828155753"
},
{
"id": 976877075,
"name": "Preview of Parallax",
"created_at": "2025-07-01T14:03:22-04:00",
"updated_at": "2025-07-01T14:03:22-04:00",
"role": "demo",
"theme_store_id": 688,
"previewable": true,
"processing": false,
"admin_graphql_api_id": "gid://shopify/Theme/976877075"
},
{
"id": 752253240,
"name": "Sandbox",
"created_at": "2025-07-01T14:03:22-04:00",
"updated_at": "2025-07-01T14:03:22-04:00",
"role": "unpublished",
"theme_store_id": null,
"previewable": true,
"processing": false,
"admin_graphql_api_id": "gid://shopify/Theme/752253240"
}
]
}

Anchor to GET request, Retrieves a single theme by its ID
get
Retrieves a single theme by its ID

theme

Retrieves a single theme by its ID.

Anchor to Parameters of Retrieves a single theme by its IDParameters

api_version
string
required
theme_id
string
required
fields

Show only certain fields, specified by a comma-separated list of field names.

Was this section helpful?

Anchor to get-themes-theme-id-examplesExamples

Retrieve a single theme

Path parameters
theme_id=828155753
string
required
Was this section helpful?
get

/admin/api/2025-07/themes/828155753.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/themes/828155753.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"theme": {
"id": 828155753,
"name": "Comfort",
"created_at": "2025-07-01T14:03:22-04:00",
"updated_at": "2025-07-01T14:03:22-04:00",
"role": "main",
"theme_store_id": null,
"previewable": true,
"processing": false,
"admin_graphql_api_id": "gid://shopify/Theme/828155753"
}
}

Anchor to PUT request, Modify an existing Theme
put
Modify an existing Theme

themeUpdate
themePublish

Updates an existing theme.

Anchor to Parameters of Modify an existing ThemeParameters

api_version
string
required
theme_id
string
required
Was this section helpful?

Anchor to put-themes-theme-id-examplesExamples

Publish an unpublished theme

Path parameters
theme_id=752253240
string
required
Request body
theme
Theme resource
Show theme properties
theme.id:752253240
read-only

The unique numeric identifier for the theme.

theme.role:"main"

Specifies how the theme is being used within the shop. Valid values:

Show role properties
  • main: The theme is published. Customers see it when they visit the online store.
  • unpublished: The theme is unpublished. Customers can't see it.
  • demo: The theme is installed on the store as a demo. The theme can't be published until the merchant buys the full version.
  • development: The theme is used for development. The theme can't be published, and is temporary.

Update a theme's name

Path parameters
theme_id=752253240
string
required
Request body
theme
Theme resource
Show theme properties
theme.id:752253240
read-only

The unique numeric identifier for the theme.

theme.name:"Experimental"

The name of the theme.

Was this section helpful?
put

/admin/api/2025-07/themes/752253240.json

curl -d '{"theme":{"id":752253240,"role":"main"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-07/themes/752253240.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"theme": {
"role": "main",
"id": 752253240,
"name": "Sandbox",
"created_at": "2025-07-01T14:03:22-04:00",
"updated_at": "2025-07-01T14:04:27-04:00",
"theme_store_id": null,
"previewable": true,
"processing": false,
"admin_graphql_api_id": "gid://shopify/Theme/752253240"
}
}

Anchor to DELETE request, Remove an existing Theme
del
Remove an existing Theme

themeDelete

Deletes a theme. A theme can't be deleted while it's uploading, updating, or if the theme is the last published theme.

Anchor to Parameters of Remove an existing ThemeParameters

api_version
string
required
theme_id
string
required
Was this section helpful?

Anchor to delete-themes-theme-id-examplesExamples

Delete a theme

Path parameters
theme_id=752253240
string
required
Was this section helpful?
del

/admin/api/2025-07/themes/752253240.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/themes/752253240.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"id": 752253240,
"name": "Sandbox",
"created_at": "2025-07-01T14:03:22-04:00",
"updated_at": "2025-07-01T14:03:22-04:00",
"role": "unpublished",
"theme_store_id": null,
"previewable": true,
"processing": false,
"admin_graphql_api_id": "gid://shopify/Theme/752253240"
}