We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Theme

Version 2019-04

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 the files of a theme after it has been uploaded, use the Asset resource. To learn how to create your own theme, see Building themes

What you can do with Theme

The Shopify API lets you do the following with the Theme resource. More detailed versions of these general actions may be available:

Theme properties

created_at
read-only
"created_at": "2012-08-24T14:01:47-04:00"

The date and time (ISO 8601 format) when the theme was created.

id
read-only
"id": 828155753

A unique numeric identifier for the theme.

name
"name": "Comfort"

The name of the theme.

previewable
read-only
"previewable": true

Whether the theme can currently be previewed.

processing
read-only
"processing": true

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

role
"role": "main"

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

  • 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.
theme_store_id
read-only
"theme_store_id": 775

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
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time ( ISO 8601 format) when the theme was last updated.

Endpoints

GET /admin/api/2019-07/themes.json
Retrieves a list of themes.
fields

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

Retrieve a list of themes

GET /admin/api/#{api_version}/themes.json
View Response
HTTP/1.1 200 OK
{
  "themes": [
    {
      "id": 828155753,
      "name": "Comfort",
      "created_at": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-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": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-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": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-04:00",
      "role": "unpublished",
      "theme_store_id": null,
      "previewable": true,
      "processing": false,
      "admin_graphql_api_id": "gid://shopify/Theme/752253240"
    }
  ]
}
GET /admin/api/2019-07/themes/828155753.json
Retrieves a single theme.
fields

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

Retrieve a single theme

GET /admin/api/#{api_version}/themes/#{theme_id}.json
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 828155753,
    "name": "Comfort",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:27:39-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/828155753"
  }
}
POST /admin/api/2019-07/themes.json
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.

Create a theme that has a custom name and is published

POST /admin/api/#{api_version}/themes.json
{
  "theme": {
    "name": "Lemongrass",
    "src": "http://themes.shopify.com/theme.zip",
    "role": "main"
  }
}
View Response
HTTP/1.1 201 Created
{
  "theme": {
    "id": 1049083724,
    "name": "Lemongrass",
    "created_at": "2019-07-22T11:39:55-04:00",
    "updated_at": "2019-07-22T11:39:55-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": false,
    "processing": true,
    "admin_graphql_api_id": "gid://shopify/Theme/1049083724"
  }
}

Creating a theme without a name fails and returns an error

POST /admin/api/#{api_version}/themes.json
{
  "theme": {
    "body": "foobar"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2019-07/themes/752253240.json
Updates an existing theme.

Publish an unpublished theme

PUT /admin/api/#{api_version}/themes/#{theme_id}.json
{
  "theme": {
    "id": 752253240,
    "role": "main"
  }
}
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 752253240,
    "name": "Sandbox",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:39:56-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}

Update a theme's name

PUT /admin/api/#{api_version}/themes/#{theme_id}.json
{
  "theme": {
    "id": 752253240,
    "name": "Experimental"
  }
}
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 752253240,
    "name": "Experimental",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:39:57-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}
DELETE /admin/api/2019-07/themes/752253240.json
Deletes a theme.

Delete a theme

DELETE /admin/api/#{api_version}/themes/#{theme_id}.json
View Response
HTTP/1.1 200 OK
{
  "id": 752253240,
  "name": "Sandbox",
  "created_at": "2019-07-22T11:27:39-04:00",
  "updated_at": "2019-07-22T11:27:39-04:00",
  "role": "unpublished",
  "theme_store_id": null,
  "previewable": true,
  "processing": false,
  "admin_graphql_api_id": "gid://shopify/Theme/752253240"
}
Version 2019-07 (Latest)

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 the files of a theme after it has been uploaded, use the Asset resource. To learn how to create your own theme, see Building themes

What you can do with Theme

The Shopify API lets you do the following with the Theme resource. More detailed versions of these general actions may be available:

Theme properties

created_at
read-only
"created_at": "2012-08-24T14:01:47-04:00"

The date and time (ISO 8601 format) when the theme was created.

id
read-only
"id": 828155753

A unique numeric identifier for the theme.

name
"name": "Comfort"

The name of the theme.

previewable
read-only
"previewable": true

Whether the theme can currently be previewed.

processing
read-only
"processing": true

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

role
"role": "main"

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

  • 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.
theme_store_id
read-only
"theme_store_id": 775

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
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time ( ISO 8601 format) when the theme was last updated.

Endpoints

GET /admin/api/2019-07/themes.json
Retrieves a list of themes.
fields

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

Retrieve a list of themes

GET /admin/api/#{api_version}/themes.json
View Response
HTTP/1.1 200 OK
{
  "themes": [
    {
      "id": 828155753,
      "name": "Comfort",
      "created_at": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-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": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-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": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-04:00",
      "role": "unpublished",
      "theme_store_id": null,
      "previewable": true,
      "processing": false,
      "admin_graphql_api_id": "gid://shopify/Theme/752253240"
    }
  ]
}
GET /admin/api/2019-07/themes/828155753.json
Retrieves a single theme.
fields

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

Retrieve a single theme

GET /admin/api/#{api_version}/themes/#{theme_id}.json
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 828155753,
    "name": "Comfort",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:27:39-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/828155753"
  }
}
POST /admin/api/2019-07/themes.json
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.

Create a theme that has a custom name and is published

POST /admin/api/#{api_version}/themes.json
{
  "theme": {
    "name": "Lemongrass",
    "src": "http://themes.shopify.com/theme.zip",
    "role": "main"
  }
}
View Response
HTTP/1.1 201 Created
{
  "theme": {
    "id": 1049083724,
    "name": "Lemongrass",
    "created_at": "2019-07-22T11:39:55-04:00",
    "updated_at": "2019-07-22T11:39:55-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": false,
    "processing": true,
    "admin_graphql_api_id": "gid://shopify/Theme/1049083724"
  }
}

Creating a theme without a name fails and returns an error

POST /admin/api/#{api_version}/themes.json
{
  "theme": {
    "body": "foobar"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2019-07/themes/752253240.json
Updates an existing theme.

Publish an unpublished theme

PUT /admin/api/#{api_version}/themes/#{theme_id}.json
{
  "theme": {
    "id": 752253240,
    "role": "main"
  }
}
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 752253240,
    "name": "Sandbox",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:39:56-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}

Update a theme's name

PUT /admin/api/#{api_version}/themes/#{theme_id}.json
{
  "theme": {
    "id": 752253240,
    "name": "Experimental"
  }
}
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 752253240,
    "name": "Experimental",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:39:57-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}
DELETE /admin/api/2019-07/themes/752253240.json
Deletes a theme.

Delete a theme

DELETE /admin/api/#{api_version}/themes/#{theme_id}.json
View Response
HTTP/1.1 200 OK
{
  "id": 752253240,
  "name": "Sandbox",
  "created_at": "2019-07-22T11:27:39-04:00",
  "updated_at": "2019-07-22T11:27:39-04:00",
  "role": "unpublished",
  "theme_store_id": null,
  "previewable": true,
  "processing": false,
  "admin_graphql_api_id": "gid://shopify/Theme/752253240"
}
Version 2019-10 (Release candidate)

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 the files of a theme after it has been uploaded, use the Asset resource. To learn how to create your own theme, see Building themes

What you can do with Theme

The Shopify API lets you do the following with the Theme resource. More detailed versions of these general actions may be available:

Theme properties

created_at
read-only
"created_at": "2012-08-24T14:01:47-04:00"

The date and time (ISO 8601 format) when the theme was created.

id
read-only
"id": 828155753

A unique numeric identifier for the theme.

name
"name": "Comfort"

The name of the theme.

previewable
read-only
"previewable": true

Whether the theme can currently be previewed.

processing
read-only
"processing": true

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

role
"role": "main"

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

  • 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.
theme_store_id
read-only
"theme_store_id": 775

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
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time ( ISO 8601 format) when the theme was last updated.

Endpoints

GET /admin/api/2019-07/themes.json
Retrieves a list of themes.
fields

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

Retrieve a list of themes

GET /admin/api/#{api_version}/themes.json
View Response
HTTP/1.1 200 OK
{
  "themes": [
    {
      "id": 828155753,
      "name": "Comfort",
      "created_at": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-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": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-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": "2019-07-22T11:27:39-04:00",
      "updated_at": "2019-07-22T11:27:39-04:00",
      "role": "unpublished",
      "theme_store_id": null,
      "previewable": true,
      "processing": false,
      "admin_graphql_api_id": "gid://shopify/Theme/752253240"
    }
  ]
}
GET /admin/api/2019-07/themes/828155753.json
Retrieves a single theme.
fields

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

Retrieve a single theme

GET /admin/api/#{api_version}/themes/#{theme_id}.json
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 828155753,
    "name": "Comfort",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:27:39-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/828155753"
  }
}
POST /admin/api/2019-07/themes.json
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.

Create a theme that has a custom name and is published

POST /admin/api/#{api_version}/themes.json
{
  "theme": {
    "name": "Lemongrass",
    "src": "http://themes.shopify.com/theme.zip",
    "role": "main"
  }
}
View Response
HTTP/1.1 201 Created
{
  "theme": {
    "id": 1049083724,
    "name": "Lemongrass",
    "created_at": "2019-07-22T11:39:55-04:00",
    "updated_at": "2019-07-22T11:39:55-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": false,
    "processing": true,
    "admin_graphql_api_id": "gid://shopify/Theme/1049083724"
  }
}

Creating a theme without a name fails and returns an error

POST /admin/api/#{api_version}/themes.json
{
  "theme": {
    "body": "foobar"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "name": [
      "can't be blank"
    ]
  }
}
PUT /admin/api/2019-07/themes/752253240.json
Updates an existing theme.

Publish an unpublished theme

PUT /admin/api/#{api_version}/themes/#{theme_id}.json
{
  "theme": {
    "id": 752253240,
    "role": "main"
  }
}
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 752253240,
    "name": "Sandbox",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:39:56-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}

Update a theme's name

PUT /admin/api/#{api_version}/themes/#{theme_id}.json
{
  "theme": {
    "id": 752253240,
    "name": "Experimental"
  }
}
View Response
HTTP/1.1 200 OK
{
  "theme": {
    "id": 752253240,
    "name": "Experimental",
    "created_at": "2019-07-22T11:27:39-04:00",
    "updated_at": "2019-07-22T11:39:57-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}
DELETE /admin/api/2019-07/themes/752253240.json
Deletes a theme.

Delete a theme

DELETE /admin/api/#{api_version}/themes/#{theme_id}.json
View Response
HTTP/1.1 200 OK
{
  "id": 752253240,
  "name": "Sandbox",
  "created_at": "2019-07-22T11:27:39-04:00",
  "updated_at": "2019-07-22T11:27:39-04:00",
  "role": "unpublished",
  "theme_store_id": null,
  "previewable": true,
  "processing": false,
  "admin_graphql_api_id": "gid://shopify/Theme/752253240"
}

Sign up for a Partner account to get started.

Sign up