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, the types of updates, and the impact of breaking changes.

Theme Update Process

You can submit your updates for review as ZIP files through your Partner Dashboard. Submit routine updates (such as maintenance and bug fixes) separately from potentially breaking changes (such as feature updates and larger-scale development). Separating your routine fixes from larger updates ensures that your routine update is likely to qualify for mass upgrade, and will be made available to a greater number of merchants who have purchased your theme.

When submitting your updates, consider the hours of operation in Eastern Standard Time (EST) as it might impact the timeliness of the attention your update receives. 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.

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.

Mass upgrade

A mass upgrade is when a new version of a theme replaces the current published version of the theme that merchants have installed. Themes are mass upgraded by default unless the changes contain a breaking change.

Frequently asked questions about mass upgrades

  • In a theme installed from the Theme Store, if I edit a file, then edit it back to the way it was before, is it still mass-upgradable? Yes.

  • In a theme installed from the Theme Store, if I upload my logo on the Online Store Editor page, is my theme still mass-upgradable? Yes, if the theme is using files/image picker.

  • If I upload a theme from my computer, which is identical to one in the theme store, except with a different name, then is my theme mass-upgradable? Yes.

  • If the images in the /assets/ directory for my theme are changed from its original installed state, is my theme mass-upgradable? No.

Breaking changes

A breaking change is a update to your theme that can cause other components of your theme to fail. For example, if you change a setting variable name in a theme and the theme is mass upgraded, then it could potentially break the theme on a merchant’s store. In this example, the settings would be reset to their initial state and the merchant would lose their changes. Breaking changes shouldn’t be mass upgraded. Breaking changes can be accepted to the Theme Store for future downloads, but they won’t be mass-upgraded to existing merchants.

Examples of breaking and non-breaking changes

The following examples are scenarios that help illustrate when a change could result in a theme that shouldn't be mass-upgraded.

Scenario A

You remove a theme setting and all references to it in the theme files. This isn't a breaking change. Having extra or unused values in the settings_data.json won't break the theme.

Scenario B

You add a theme setting and make reference to it in the SCSS files. This might be a breaking change. If a setting value doesn't exist in settings_data.json, then the SCSS file will fail to compile. However, this situation can be avoided by having a default value in settings_schema.json (or wherever the setting value is created).

Scenario C

You add a theme setting and make reference to it in the theme template files. This might be a breaking change. It depends on the Liquid filters that you use. For example, if you use the downcase or color_to_rgb filters on a setting that doesn't exist, then this is not a breaking change.

When you're adding settings, you have to be concerned about breaking changes when you're using filters. There won't be a value initially because the settings_data.json file is untouched at update.

Scenario D

You change the type of an input, but keep the id the same. This is likely a breaking change. When you change only the type, such as a text input to a video input, then you're likely changing your theme files to use the expected properties of the new input. However, these properties won't exist for current merchant themes because their settings_data.json file is referencing the wrong type of resource.