How to update a customised Shopify theme without losing changes

Your admin says a new version of your theme is available, but a developer has customised it: a size guide section, a change to the cart, some CSS. The worry is that updating throws that work away. Adding an update never changes your live store, but whether your changes come across depends on how they were made.

What happens when you update a Shopify theme?

Shopify adds the new version as a separate draft theme and leaves your live theme as it is. For a Shopify Theme Store theme, a notification replaces the version number in your admin when an update is out. Click it, read the release notes and choose Add to draft themes. The copy is named "Updated copy of" your theme, and shoppers see nothing new until you publish it.

What carries over to the new version, and what doesn't?

Theme editor changes carry over; code edits carry over only when they don't conflict with the update. Shopify copies these into the updated theme:

• Theme settings, such as colours and fonts.
• Page layouts: sections and blocks you added, moved, hid or removed.
• Section and block settings, including images, video, text and dynamic sources.
• Templates you created in the theme editor.
• App embeds and app extensions, including their settings.
• Wording you changed with the theme content editor.

Code edits are the weak point, whether a developer made them in the code editor or an app made them for you. Once the update is added, the theme card says either code edits successfully included or code edits could not be included. In the second case, Shopify's code editor guidance says all your code changes are removed from the updated copy. Your current theme still has them, but someone has to copy them across by hand.

Why do code edits get in the way of updates?

Because your developer's edits and the theme designer's new version change the same files, and Shopify only brings edits across when the two don't clash. That is why Shopify advises editing code only when neither an app nor the theme editor can do the job. Three things to watch:

• Edits inside the theme's original files, which the new version may have rewritten.
• Schema changes, such as raising the block limit of a section. Shopify warns that changing limits and constraints in a theme's schema might make the update fail.
• Custom CSS that targets the theme's class names. Shopify notes that an update can stop custom CSS working, so check that the selectors still exist.

How do you keep a customised theme upgrade-safe?

Keep as much as you can in the places an update copies across, and write down everything else. In practice:

• Use the theme's own settings, sections and blocks first. Our guide to Online Store 2.0 sections shows what they can do.
• Choose apps built with theme app extensions. You place their app blocks and app embeds in the theme editor, they don't edit theme code, and their settings carry over.
• When code is unavoidable, we add new section or snippet files rather than rewriting the theme's originals, so each change is easy to find and reapply.
• Keep a changelog of every code edit: the file, what changed, why, and the date.

Shopify recommends saving a copy of any customised code before you update, even when you expect the edits to come across.

How do you test the update before it goes live?

Do all the work on the updated draft copy, and publish only when it passes. Our order:

1. Duplicate the live theme as a backup.
2. Add the update to your draft themes and note which code edits message appears.
3. Reapply any missing edits on the draft copy, working from the changelog.
4. Preview the draft and walk a real purchase path: home, collection, product, cart and on to checkout. A preview opened from the admin has access to checkout.
5. Repeat that path on a real phone, not just a narrow desktop window.
6. Check every page where an app appears and confirm it still works. Shopify warns that some apps might not be compatible with a new theme.
7. Publish at a quiet time for your store.

For a colleague's sign-off, share a visitor preview link from the preview bar. It needs no admin login and expires after two days.

Should your developer use GitHub and Shopify CLI?

Yes, if anyone edits your theme code more than occasionally. The code editor's Timeline restores earlier versions one file at a time, and its history is finite. Version control keeps the whole record.

The Shopify GitHub integration connects a theme to a branch of a GitHub repository. Commits to the branch update the theme, and changes saved in the admin, theme editor included, are committed back, so the two always match. With Shopify CLI, a developer downloads a theme with shopify theme pull, previews local changes on a hidden development theme with shopify theme dev, and uploads work as a new unpublished theme with shopify theme push --unpublished. Shopify suggests using the two together, so every change has a dated record to work from when an update leaves edits behind.

Where to start

In your admin, go to Online Store and click your live theme's version number to check its status and read the release notes. Then ask whoever customised the theme for a list of every code edit. If none exists, writing it is the first job. Our Shopify stores service can run the update on a draft copy and reapply your custom code, or tell us your theme and version.