---
title: Theme
description: >-
  Manage a store's themes, which control the look and feel of an online store.
  Use the Asset API to update specific files within a theme.
api_version: 2026-07
source_url:
  html: 'https://shopify.dev/docs/api/admin-rest/latest/resources/theme'
  md: 'https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md'
api_name: admin-rest
api_type: rest
---

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](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate).

# Theme

**Requires \`themes\` access scope.:**

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

![](https://shopify.dev/assets/api/reference/theme.png)

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](https://shopify.dev/docs/admin-api/rest/reference/online-store/asset) resource. To learn how to create your own theme, refer to [*Building themes*](https://shopify.dev/concepts/themes)

\#

## Endpoints

* [post](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#post-themes)

  [/admin/api/latest/themes.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#post-themes)

  Creates a theme

  [themeCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeCreate?example=creates-a-theme)

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#get-themes)

  [/admin/api/latest/themes.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#get-themes)

  Retrieves a list of themes

  [themes](https://shopify.dev/docs/api/admin-graphql/latest/queries/themes?example=retrieves-a-list-of-themes)

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#get-themes-theme-id)

  [/admin/api/latest/themes/{theme\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#get-themes-theme-id)

  Retrieves a single theme by its ID

  [theme](https://shopify.dev/docs/api/admin-graphql/latest/queries/theme?example=retrieves-a-single-theme-by-its-id)

* [put](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#put-themes-theme-id)

  [/admin/api/latest/themes/{theme\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#put-themes-theme-id)

  Modify an existing Theme

  [themeUpdate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeUpdate)

  [themePublish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themePublish?example=modify-an-existing-theme)

* [del](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#delete-themes-theme-id)

  [/admin/api/latest/themes/{theme\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/theme.md#delete-themes-theme-id)

  Remove an existing Theme

  [themeDelete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeDelete?example=remove-an-existing-theme)

***

## The Theme resource

### Properties

***

created\_at

**read-only**

->[createdAt](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.createdAt)

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

***

id

**read-only**

->[id](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.id)

The unique numeric identifier for the theme.

***

name

->[name](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.name)

The name of the theme.

***

previewable

**read-only**

**deprecated**

Whether the theme can currently be previewed.

***

processing

**read-only**

->[processing](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.processing)

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

***

role

->[role](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.role)

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.
* **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](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.themeStoreId)

A unique identifier applied to Shopify-made themes that are installed from the [Shopify Theme Store](https://themes.shopify.com/) 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme#field-OnlineStoreTheme.fields.updatedAt)

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

***

{}

## The Theme resource

```json
{
  "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"
}
```

***

## postCreates a theme

[themeCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeCreate?example=creates-a-theme)

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.

### Parameters

***

api\_version

**string**

**required**

***

### Examples

### Create a theme that has a custom name and is published

### Request body

theme​

**Theme resource**

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:

* **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

post

## /admin/api/2026-07/themes.​json

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

{}

## Response

JSON

```json
HTTP/1.1 201 Created
{
  "theme": {
    "id": 1049083724,
    "name": "Lemongrass",
    "created_at": "2026-07-02T10:42:09-04:00",
    "updated_at": "2026-07-02T10:42:09-04:00",
    "role": "unpublished",
    "theme_store_id": null,
    "previewable": false,
    "processing": true,
    "admin_graphql_api_id": "gid://shopify/Theme/1049083724"
  }
}
```

### examples

* #### Create a theme that has a custom name and is published

  #####

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

  #### response

  ```json
  HTTP/1.1 201 Created{"theme":{"id":1049083724,"name":"Lemongrass","created_at":"2026-07-02T10:42:09-04:00","updated_at":"2026-07-02T10:42:09-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

  #####

  ```curl
  curl -d '{"theme":{"body":"foobar"}}' \
  -X POST "https://your-development-store.myshopify.com/admin/api/2026-07/themes.json" \
  -H "X-Shopify-Access-Token: {access_token}" \
  -H "Content-Type: application/json"
  ```

  #### response

  ```json
  HTTP/1.1 422 Unprocessable Entity{"errors":{"name":["can't be blank"]}}
  ```

***

## getRetrieves a list of themes

[themes](https://shopify.dev/docs/api/admin-graphql/latest/queries/themes?example=retrieves-a-list-of-themes)

Retrieves a list of themes.

### Parameters

***

api\_version

**string**

**required**

***

fields

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

***

### Examples

### Retrieve a list of themes

get

## /admin/api/2026-07/themes.​json

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

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "themes": [
    {
      "id": 828155753,
      "name": "Comfort",
      "created_at": "2026-07-02T10:36:00-04:00",
      "updated_at": "2026-07-02T10:36:00-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": "2026-07-02T10:36:00-04:00",
      "updated_at": "2026-07-02T10:36:00-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": "2026-07-02T10:36:00-04:00",
      "updated_at": "2026-07-02T10:36:00-04:00",
      "role": "unpublished",
      "theme_store_id": null,
      "previewable": true,
      "processing": false,
      "admin_graphql_api_id": "gid://shopify/Theme/752253240"
    }
  ]
}
```

### examples

* #### Retrieve a list of themes

  #####

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

  #### response

  ```json
  HTTP/1.1 200 OK{"themes":[{"id":828155753,"name":"Comfort","created_at":"2026-07-02T10:36:00-04:00","updated_at":"2026-07-02T10:36:00-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":"2026-07-02T10:36:00-04:00","updated_at":"2026-07-02T10:36:00-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":"2026-07-02T10:36:00-04:00","updated_at":"2026-07-02T10:36:00-04:00","role":"unpublished","theme_store_id":null,"previewable":true,"processing":false,"admin_graphql_api_id":"gid://shopify/Theme/752253240"}]}
  ```

***

## getRetrieves a single theme by its ID

[theme](https://shopify.dev/docs/api/admin-graphql/latest/queries/theme?example=retrieves-a-single-theme-by-its-id)

Retrieves a single theme by its ID.

### Parameters

***

api\_version

**string**

**required**

***

theme\_id

**string**

**required**

***

fields

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

***

### Examples

### Retrieve a single theme

### Path parameters

theme\_​id=​828155753

**string**

**required**

get

## /admin/api/2026-07/themes/828155753.​json

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

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "theme": {
    "id": 828155753,
    "name": "Comfort",
    "created_at": "2026-07-02T10:36:00-04:00",
    "updated_at": "2026-07-02T10:36:00-04:00",
    "role": "main",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/828155753"
  }
}
```

### examples

* #### Retrieve a single theme

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-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":"2026-07-02T10:36:00-04:00","updated_at":"2026-07-02T10:36:00-04:00","role":"main","theme_store_id":null,"previewable":true,"processing":false,"admin_graphql_api_id":"gid://shopify/Theme/828155753"}}
  ```

***

## putModify an existing Theme

[themeUpdate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeUpdate)

[themePublish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themePublish?example=modify-an-existing-theme)

Updates an existing theme.

### Parameters

***

api\_version

**string**

**required**

***

theme\_id

**string**

**required**

***

### Examples

### Publish an unpublished theme

### Path parameters

theme\_​id=​752253240

**string**

**required**

### Request body

theme​

**Theme resource**

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:

* **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**

theme.id:​752253240

**read-only**

The unique numeric identifier for the theme.

theme.name:​"Experimental"

The name of the theme.

put

## /admin/api/2026-07/themes/752253240.​json

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

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "theme": {
    "role": "main",
    "name": "Sandbox",
    "id": 752253240,
    "created_at": "2026-07-02T10:36:00-04:00",
    "updated_at": "2026-07-02T10:42:10-04:00",
    "theme_store_id": null,
    "previewable": true,
    "processing": false,
    "admin_graphql_api_id": "gid://shopify/Theme/752253240"
  }
}
```

### examples

* #### Publish an unpublished theme

  #####

  ```curl
  curl -d '{"theme":{"id":752253240,"role":"main"}}' \
  -X PUT "https://your-development-store.myshopify.com/admin/api/2026-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","name":"Sandbox","id":752253240,"created_at":"2026-07-02T10:36:00-04:00","updated_at":"2026-07-02T10:42:10-04:00","theme_store_id":null,"previewable":true,"processing":false,"admin_graphql_api_id":"gid://shopify/Theme/752253240"}}
  ```

* #### Update a theme's name

  #####

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

***

## delRemove an existing Theme

[themeDelete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeDelete?example=remove-an-existing-theme)

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

### Parameters

***

api\_version

**string**

**required**

***

theme\_id

**string**

**required**

***

### Examples

### Delete a theme

### Path parameters

theme\_​id=​752253240

**string**

**required**

del

## /admin/api/2026-07/themes/752253240.​json

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

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "id": 752253240,
  "name": "Sandbox",
  "created_at": "2026-07-02T10:36:00-04:00",
  "updated_at": "2026-07-02T10:36:00-04:00",
  "role": "unpublished",
  "theme_store_id": null,
  "previewable": true,
  "processing": false,
  "admin_graphql_api_id": "gid://shopify/Theme/752253240"
}
```

### examples

* #### Delete a theme

  #####

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

  #### response

  ```json
  HTTP/1.1 200 OK{"id":752253240,"name":"Sandbox","created_at":"2026-07-02T10:36:00-04:00","updated_at":"2026-07-02T10:36:00-04:00","role":"unpublished","theme_store_id":null,"previewable":true,"processing":false,"admin_graphql_api_id":"gid://shopify/Theme/752253240"}
  ```