Updating your theme
After you've first published a theme on the Theme Store, you begin the iterative process of considering merchant feedback, persistently innovating your build through regular quality assurance testing, and actively integrating the updates required by Shopify.
As a Shopify Theme Partner, you're required to provide ongoing updates to your theme to remain on the Shopify Theme Store.
The following sections describe the theme update process and the types of updates.
Theme update process
Anchor link to section titled "Theme update process"You can submit your updates for review as ZIP files through your Partner Dashboard. Each update should have a version number, determined by the content of the update, and release notes.
Depending on the version type that's being released, there are two ways that a merchant's theme can be updated:
- Merchants are shown a notification on the Online store > Themes page letting them know that they can update their theme. The merchant can apply the update to an unpublished copy of their theme so that they can review it before publishing.
- The theme is automatically updated.
Because different version types potentially have different update processes, you should group changes based on version types as much as possible. Grouping changes can help ensure that a greater number of merchants who have purchased your theme receive as many automatic updates as possible.
When submitting your updates, consider the hours of operation in Eastern Standard Time (EST) as it might impact how quickly merchants receive and apply your updates. Crucial updates are best submitted earlier in the week, as well as earlier in the business day. Updates mandated by Shopify might be required by a deadline to accommodate a feature’s release date.
After your update has been successfully reviewed and published, you receive an automatic notification email.
Considerations for new versions
Anchor link to section titled "Considerations for new versions"Consider the following, and the associated merchant impact, when creating new versions:
- If you change an existing setting so that the merchant's value is no longer valid, then the merchant's value will be reset to the default, as specified in your new version. To create less friction for existing merchants, you should keep the same default settings when possible.
- If you change the ID of a setting, then the setting in the current theme will be considered as removed and the new setting will be added with the default value. This provides a poor merchant experience and should be avoided.
- If you change the type of a setting, then the merchant's current setting values might be invalidated and reset to the default value.
- If you change the class of a section or change a CSS class name, then a merchant's custom CSS might be invalidated. You should avoid renaming existing classes unless necessary, and document any of these changes in your release notes.
Theme versions help merchants easily identify which theme they have, so that they can determine which features are available, or if there are more recent versions to update to.
When building your version string, you should use semantic versioning in the format of X.Y.Z
.
Component | Description |
---|---|
X |
Represents a major version that introduces or modifies features that aren't backwards compatible, such as the following:
For example, you might move from When a major version is released, merchants that have themes that don't update automatically are shown a notification on the Online store > Themes page, letting them know that they can apply the update to an unpublished copy of their theme to be reviewed and published. |
Y |
Represents a minor version that introduces or modifies features that are backwards compatible, such as the following:
For example, you might move from When a minor version is released, merchants that have themes that don't update automatically are shown a notification on the Online store > Themes page, letting them know that they can apply the update to an unpublished copy of their theme to be reviewed and published. |
Z |
Represents a maintenance version that fixes bugs or security issues, or makes non-visual code improvements. For example, you might move from When a maintenance version is released, merchant themes can be automatically updated. |
The theme version can be included in the theme through theme metadata.
Release notes
Anchor link to section titled "Release notes"For each theme version, you need to have release notes that highlight the main features of the version.
The main audience for release notes is merchants, so the language you use should reflect that. Release notes aren't intended to be a changelog, but rather a curated list of items that will impact merchants, or their buyers. As such, any user-facing changes should be included, and developer-facing changes should be excluded. You should also include only information related to the current release.
Include release notes in your theme
Anchor link to section titled "Include release notes in your theme"To include release notes with your theme, create a markdown file in the root of your theme's ZIP called release-notes.md
.
The file's contents should contain the following components:
Component | Description |
---|---|
Description | A summarized description of the most important changes in this version. |
List of changes |
A list of changes contained in the version. Changes can fall under one of the following headings:
Changes should be listed in bullet point under their respective heading. Each heading should be treated as an H3, so needs to be preceded by
If there are specific changes that you want to bring attention to, then you can prepend the change with
When the release notes are rendered, these important changes will be visually highlighted. |

Urgent updates
Anchor link to section titled "Urgent updates"An urgent update is a theme update that merchants require immediately to run their business without interruption. Typically, only updates that address an issue with the purchase flow are considered urgent. The purchase flow is the process that a customer undertakes when making a purchase, starting from the product page and continuing to checkout through the dynamic checkout button, or continuing from the cart to checkout through the checkout call-to-action or dynamic checkout buttons.
If you have an update that you deem to be important that doesn't affect the purchase flow, then you can consult your Theme Partner Manager before you submit the update.
Automated updates
Anchor link to section titled "Automated updates"When maintenance versions are released, merchant themes can be automatically updated. In this case, the new version of the theme replaces the current published version that merchant has installed.
A theme will be automatically updated only if all theme files, except settings_data.json
and any JSON files in the /templates
directory, are in their original state. If a theme can't be automatically updated, then merchants are shown a notification on the Online store > Themes page letting them know that they can apply the update to an unpublished copy of their theme to be reviewed and published.
The following outlines some example scenarios and whether a theme would be automatically updated:
Scenario | Automated update? |
---|---|
In a new theme version, I fixed typos or adjusted the titles of labels. | Yes |
In a new theme version, I adjusted the "default" text of a setting (e.g. "Tell your story with images"). | Yes |
In a new theme version, I re-ordered sections, changing the settings_schema.json file. | Yes |
In a theme installed from the Theme Store, I edited a file, then edited it back to the way it was before. | Yes |
In a theme installed from the Theme Store, I uploaded my logo on the theme editor page through a files/image picker. | Yes |
The images in the /assets directory for my theme have changed from their original installed state. |
No |
Adding presets
Anchor link to section titled "Adding presets"Presets are default configurations of sections that enable users to easily add a section to a JSON template through the theme editor. Presets aren't related to theme styles that are defined in settings_data.json
.
Complete the following steps to update your theme so that it includes a preset:
- Edit your theme code to add the preset.
- Submit a new ZIP file through the Partner Dashboard as a theme update.
Include the new preset demo URL in the internal note.
After you've completed the update, you can edit your demo store details in the Partner Dashboard. For example, you can add demo store screenshots and preset accent colors.