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 processAnchor link to section titled "Theme update process"
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.
To avoid update fatigue for merchants, there should be a minimum of 4 weeks between updates.
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 versionsAnchor 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 may be invalidated and reset to the default value.
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
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 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.
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 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.
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 notesAnchor 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 themeAnchor 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:
|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 updatesAnchor 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 updatesAnchor 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
/locales directories, 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:
|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