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.

Versioning

Anchor link to section titled "Versioning"

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

Component	Description
`X`	Represents a major version that introduces or modifies features that aren't backwards compatible, such as the following: Modifying a settings value. Removing a setting, section, or block. Adding a global setting. For example, you might move from `1.4.8` to `2.0.0`. 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: Modifying the label or default value of an existing setting. Adding a section or block. Changing the visual design, or functionality, of an existing section or block without changing their setting schema. For example, you might move from `1.4.8` to `1.5.0`. 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 `1.4.8` to `1.4.9`. When a maintenance version is released, merchant themes can be automatically updated.

X

Represents a major version that introduces or modifies features that aren't backwards compatible, such as the following:

Modifying a settings value.
Removing a setting, section, or block.
Adding a global setting.

For example, you might move from 1.4.8 to 2.0.0.

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:

Modifying the label or default value of an existing setting.
Adding a section or block.
Changing the visual design, or functionality, of an existing section or block without changing their setting schema.

For example, you might move from 1.4.8 to 1.5.0.

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 1.4.8 to 1.4.9.

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

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: Added Changed Removed Security Other fixes and improvements 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 `###`. For example, `### Added`. If there are specific changes that you want to bring attention to, then you can prepend the change with `Important:`. For example: `- Important: This is an important change.` When the release notes are rendered, these important changes will be visually highlighted.

A list of changes contained in the version. Changes can fall under one of the following headings:

Added
Changed
Removed
Security
Other fixes and improvements

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 ###. For example, ### Added.

If there are specific changes that you want to bring attention to, then you can prepend the change with Important:. For example:

- Important: This is an important change.

When the release notes are rendered, these important changes will be visually highlighted.

Example

Anchor link to section titled "Example"

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.