--- 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: unstable api_name: admin-rest api_type: rest source_url: html: 'https://shopify.dev/docs/api/admin-rest/unstable/resources/theme' md: 'https://shopify.dev/docs/api/admin-rest/unstable/resources/theme.md' --- 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/unstable/resources/theme.md#post-themes) [/admin/api/unstable/themes.​json](https://shopify.dev/docs/api/admin-rest/unstable/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/unstable/resources/theme.md#get-themes) [/admin/api/unstable/themes.​json](https://shopify.dev/docs/api/admin-rest/unstable/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/unstable/resources/theme.md#get-themes-theme-id) [/admin/api/unstable/themes/{theme\_​id}.​json](https://shopify.dev/docs/api/admin-rest/unstable/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/unstable/resources/theme.md#put-themes-theme-id) [/admin/api/unstable/themes/{theme\_​id}.​json](https://shopify.dev/docs/api/admin-rest/unstable/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/unstable/resources/theme.md#delete-themes-theme-id) [/admin/api/unstable/themes/{theme\_​id}.​json](https://shopify.dev/docs/api/admin-rest/unstable/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: 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](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 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 post ## /admin/api/unstable/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/unstable/themes.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` {} ## Response JSON ```json HTTP/1.1 201 Created { "theme": { "id": 1049083723, "name": "Lemongrass", "created_at": "2025-10-01T14:59:25-04:00", "updated_at": "2025-10-01T14:59:25-04:00", "role": "unpublished", "theme_store_id": null, "previewable": false, "processing": true, "admin_graphql_api_id": "gid://shopify/Theme/1049083723" } } ``` ### 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/unstable/themes.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.post({ path: 'themes', data: {"theme":{"name":"Lemongrass","src":"http://themes.shopify.com/theme.zip","role":"main"}}, type: DataType.JSON, }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.post( path: 'themes', body: { "theme": { "name": "Lemongrass", "src": "http://themes.shopify.com/theme.zip", "role": "main" } }, ) ``` ##### ```node import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.post({ path: 'themes', data: {"theme":{"name":"Lemongrass","src":"http://themes.shopify.com/theme.zip","role":"main"}}, type: DataType.JSON, }); ``` #### response ```json HTTP/1.1 201 Created{"theme":{"id":1049083723,"name":"Lemongrass","created_at":"2025-10-01T14:59:25-04:00","updated_at":"2025-10-01T14:59:25-04:00","role":"unpublished","theme_store_id":null,"previewable":false,"processing":true,"admin_graphql_api_id":"gid://shopify/Theme/1049083723"}} ``` * #### 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/unstable/themes.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.post({ path: 'themes', data: {"theme":{"body":"foobar"}}, type: DataType.JSON, }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.post( path: 'themes', body: { "theme": { "body": "foobar" } }, ) ``` ##### ```node import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.post({ path: 'themes', data: {"theme":{"body":"foobar"}}, type: DataType.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/unstable/themes.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/unstable/themes.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "themes": [ { "id": 828155753, "name": "Comfort", "created_at": "2025-10-01T14:30:56-04:00", "updated_at": "2025-10-01T14:30:56-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-10-01T14:30:56-04:00", "updated_at": "2025-10-01T14:30:56-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-10-01T14:30:56-04:00", "updated_at": "2025-10-01T14:30:56-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/unstable/themes.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` ##### ```remix const client = new shopify.clients.Rest({session}); const data = await client.get({ path: 'themes', }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.get( path: 'themes', ) ``` ##### ```node const client = new shopify.clients.Rest({session}); const data = await client.get({ path: 'themes', }); ``` #### response ```json HTTP/1.1 200 OK{"themes":[{"id":828155753,"name":"Comfort","created_at":"2025-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:30:56-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-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:30:56-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-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:30:56-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/unstable/themes/828155753.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/unstable/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": "2025-10-01T14:30:56-04:00", "updated_at": "2025-10-01T14:30:56-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/unstable/themes/828155753.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` ##### ```remix const client = new shopify.clients.Rest({session}); const data = await client.get({ path: 'themes/828155753', }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.get( path: 'themes/828155753', ) ``` ##### ```node const client = new shopify.clients.Rest({session}); const data = await client.get({ path: 'themes/828155753', }); ``` #### response ```json HTTP/1.1 200 OK{"theme":{"id":828155753,"name":"Comfort","created_at":"2025-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:30:56-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 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. put ## /admin/api/unstable/themes/752253240.​json ```bash curl -d '{"theme":{"id":752253240,"role":"main"}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/unstable/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", "id": 752253240, "name": "Sandbox", "created_at": "2025-10-01T14:30:56-04:00", "updated_at": "2025-10-01T14:59:26-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/unstable/themes/752253240.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.put({ path: 'themes/752253240', data: {"theme":{"id":752253240,"role":"main"}}, type: DataType.JSON, }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.put( path: 'themes/752253240', body: { "theme": { "id": 752253240, "role": "main" } }, ) ``` ##### ```node import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.put({ path: 'themes/752253240', data: {"theme":{"id":752253240,"role":"main"}}, type: DataType.JSON, }); ``` #### response ```json HTTP/1.1 200 OK{"theme":{"role":"main","id":752253240,"name":"Sandbox","created_at":"2025-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:59:26-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/unstable/themes/752253240.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.put({ path: 'themes/752253240', data: {"theme":{"id":752253240,"name":"Experimental"}}, type: DataType.JSON, }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.put( path: 'themes/752253240', body: { "theme": { "id": 752253240, "name": "Experimental" } }, ) ``` ##### ```node import { DataType } from '@shopify/shopify-api'; const client = new shopify.clients.Rest({session}); const data = await client.put({ path: 'themes/752253240', data: {"theme":{"id":752253240,"name":"Experimental"}}, type: DataType.JSON, }); ``` #### response ```json HTTP/1.1 200 OK{"theme":{"name":"Experimental","role":"unpublished","id":752253240,"created_at":"2025-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:59:27-04:00","theme_store_id":null,"previewable":true,"processing":false,"admin_graphql_api_id":"gid://shopify/Theme/752253240"}} ``` *** ## 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/unstable/themes/752253240.​json ```bash curl -X DELETE "https://your-development-store.myshopify.com/admin/api/unstable/themes/752253240.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "id": 752253240, "name": "Sandbox", "created_at": "2025-10-01T14:30:56-04:00", "updated_at": "2025-10-01T14:30:56-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/unstable/themes/752253240.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` ##### ```remix const client = new shopify.clients.Rest({session}); const data = await client.delete({ path: 'themes/752253240', }); ``` ##### ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Rest::Admin.new( session: session ) response = client.delete( path: 'themes/752253240', ) ``` ##### ```node const client = new shopify.clients.Rest({session}); const data = await client.delete({ path: 'themes/752253240', }); ``` #### response ```json HTTP/1.1 200 OK{"id":752253240,"name":"Sandbox","created_at":"2025-10-01T14:30:56-04:00","updated_at":"2025-10-01T14:30:56-04:00","role":"unpublished","theme_store_id":null,"previewable":true,"processing":false,"admin_graphql_api_id":"gid://shopify/Theme/752253240"} ```