> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/theme-management/how-to-update-your-shopify-theme.md).

# How to update your Shopify theme

How a new version of your theme reaches your store, what it carries over, how to update a customized theme with Theme Companion, and what to check before you publish.

Keeping your theme up to date ensures your store benefits from the latest features, bug fixes, and compatibility improvements.

An update is always a new copy of the theme — it never overwrites the one your customers are looking at. Whichever route you take, you end up with a second theme in your library that you check first and publish when you are happy with it.

### What carries over when you update

How much you have to redo depends on how the new version reaches your store.

**From the update notification in your theme library.** Shopify adds the new version as a separate unpublished theme and copies your Theme Editor work into it — theme settings, section and block settings, layouts and templates. Code edits are included only where they don't clash with the new version; if they do, the copy arrives with a note that code edits could not be included, and you re-apply them by hand.

**From a fresh copy you add from the Theme Store yourself.** Nothing carries over — the new theme starts from the theme's defaults and you set it up from scratch.

**With Theme Companion.** Your Theme Editor work is carried over and never rewritten, and your code edits are carried over everywhere they do not overlap with the new version. Every overlap becomes a conflict you decide. See [Updating a customized theme with Theme Companion](#updating-a-customized-theme-with-theme-companion) below.

Two kinds of customization are easy to worry about unnecessarily, because they are stored as settings rather than as code and therefore travel with the update on any route except a fresh copy:

* Anything typed into a **Custom CSS** field, in Theme settings or in a section or block.
* Code sitting in a **Custom Liquid** or **Custom HTML** section, or in a Custom Liquid block inside another section.

Storefront wording you changed through **Edit default theme content** lives in the theme's language files, so note your edits beforehand and give a few of them a look afterwards.

{% hint style="warning" %}
**Major updates (e.g. v13.0.0 → v14.0.0) need a review before you publish.**

The theme's architecture changes: settings get renamed or removed, and sections and blocks can disappear. Your settings are still copied across, but any value the new version no longer recognises falls back to its default. Go through the new copy in the Theme Editor rather than assuming it looks the same as before.
{% endhint %}

{% hint style="info" %}
Minor updates (e.g. v13.0.0 → v13.0.1) keep the same settings, so the new copy usually looks exactly like your current theme.
{% endhint %}

***

### Update automatically ⚙️

{% stepper %}
{% step %}

#### Check notifications on Shopify

In your Shopify admin, go to **Online Store > Themes**. If a new version is available, you'll see a notification in your theme library.

<figure><img src="https://2798262541-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7SDIiatjQ7RGqq2Io8z4%2Fuploads%2FhlNUT6nl3wYA5yyG4YRu%2FScreenshot%202026-06-11%20at%2013.05.55.png?alt=media&amp;token=9cad4a20-5749-4026-a3bb-c1024ecb8dd7" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Review update details

* Click the notification to view more details about the update.
* Select **View release notes** to read what's new in the release.
  {% endstep %}

{% step %}

#### Add to theme library

Click **Add to theme** **library** to download and add the updated version to your Shopify store.

The updated version will now appear in your theme library, ready to customize and publish.
{% endstep %}
{% endstepper %}

***

### No update notification? 🔍

The notification only appears on a theme that Shopify can trace back to the Theme Store. It goes missing in three situations:

* The theme was uploaded as a ZIP file, which breaks that connection.
* Code customizations conflict with Shopify's update system.
* The theme was added by an app — including Theme Companion. Shopify registers app-installed themes as **uploaded**, so no notification ever appears on the card.

{% hint style="info" %}
The third case surprises people, because nobody uploaded anything. The theme is genuine; what is lost is only the automatic notice. From then on your updates come from the app rather than from the theme card.
{% endhint %}

If your theme is customized, use Theme Companion rather than reinstalling by hand — the manual route below carries nothing over for you.

{% stepper %}
{% step %}

#### Create a backup

Always duplicate your current theme before updating.

{% hint style="success" %}
**Steps:**

1. Go to **Online Store > Themes.**
2. Open the Actions dropdown for your current theme, select **Duplicate.**
3. Rename the duplicated file.
   {% endhint %}
   {% endstep %}

{% step %}

#### Install the latest theme version

{% hint style="success" %}
**Steps:**

1. Visit the Shopify Theme Store and find your them&#x65;**.**
2. Click **Add a new copy** to add the latest version.
   {% endhint %}
   {% endstep %}

{% step %}

#### Transfer your settings

{% hint style="warning" icon="octagon-exclamation" %}
**Major update (e.g. v13 → v14)**

Do NOT copy the `settings_data.json` file. The architecture has changed — pasting old code will break the new theme and cause errors in Theme Editor.

**Reconfigure your Theme Settings (Colors, Typography) manually in the Theme Editor.**
{% endhint %}

{% hint style="success" %}
**Minor update (e.g. v13.0.0 → v13.0.1)**

You can safely copy `settings_data.json` from the `Config` folder of your old theme into the new one via **Edit code**.
{% endhint %}

<figure><img src="https://2798262541-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7SDIiatjQ7RGqq2Io8z4%2Fuploads%2Fdnpg9VPx6INFJKaRJ2GV%2FScreenshot%202026-06-11%20at%2013.13.56.png?alt=media&amp;token=7db8e9b1-8ab0-4fc5-b22d-7d64bf846d85" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2798262541-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7SDIiatjQ7RGqq2Io8z4%2Fuploads%2FykKls864laJiBIeDESiI%2FScreenshot%202026-06-11%20at%2013.14.55.png?alt=media&amp;token=bb042f62-3b64-47ff-b21b-186ce3a443c9" alt=""><figcaption></figcaption></figure>

**For custom page templates:** Re-create your custom templates in the new theme — they won't exist there by default. Create a template with the exact same name, then copy the contents of the JSON file from the `Templates` folder of your old theme.
{% endstep %}

{% step %}

#### Re-install apps

Apps that add code to your theme files will need to be reinstalled or re-enabled in the new version.

{% hint style="info" %}
Find the app documentation in the [App Store](https://apps.shopify.com/) to follow the installation instructions.

If you're unfamiliar with this process, you can go to **Apps >** click **View details** to find the support email for that Shopify app.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### Updating a customized theme with Theme Companion

[Theme Companion](https://apps.shopify.com/theme-companion) is our Shopify app, and its **Theme updates** module is built for the awkward case: a customized theme, where the built-in update would leave your code edits behind. It compares three versions of every file — the theme as we shipped it, your copy with your changes, and the new release — and merges them. Avante and Volume and their presets are supported.

The app works on a separate theme in your library, so your live theme is untouched and you can cancel at any point. When the merge is done it shows you three groups — **Files with conflicts**, **Files with customizations not present in the updated version**, and **Successfully updated files with customizations** — and you either take **Apply new theme changes**, which keeps your customizations everywhere they fit and lets the new code win in the overlapping spots, or review the conflicts file by file. Publishing stays a manual step in **Online Store → Themes**; the app never publishes anything.

Two things worth knowing in advance:

* **A “Blocks preview” badge** on a file means the code has diverged too far for the theme to be assembled until you resolve it. One such file is routine; several at once mean a heavy update that may need a developer.
* **Files with customizations not present in the updated version.** When we restructure a theme between releases, a file you customized may no longer exist in the new version. It is kept, but the theme may no longer load it — so after updating, check the pages that file used to affect.

{% hint style="info" %}
Full instructions for the app, including every conflict screen, live in the [Theme Companion documentation](https://staylime.com/docs/theme-companion/theme-updates/how-theme-updates-work.md).
{% endhint %}

{% hint style="warning" %}
The longer you postpone, the harder it gets: one or two versions behind is usually a few clicks, while a long jump means your copy and ours have drifted apart and some customizations have to be re-applied by hand. If your theme is heavily customized and several versions old, involve the developer who made those customizations.
{% endhint %}

***

### Themes edited in Shopify Canvas

A theme you edited or created in Shopify Canvas does not receive theme updates at all, and Theme Companion can see it but cannot update it. If you want to keep taking new versions, keep your live theme as a standard theme — see [Shopify Canvas vs the standard theme editor](https://staylime.com/docs/getting-started/shopify-canvas-vs-the-standard-theme-editor.md).

***

### After the update

{% hint style="warning" %}
Before you publish, walk the storefront in preview: home, a collection, a product page and the cart, on both desktop and mobile. Check anything an app injects into the theme — reviews, subscriptions, currency switchers — since those are the parts most likely to need reinstalling.
{% endhint %}

New sections, blocks and settings from a release do not switch themselves on, so it is worth a look around the Theme Editor afterwards. What is new in each version is listed in the release notes for [Avante](https://staylime.com/docs/avante-themes/changelog/avante-release-notes.md) and for [Volume](https://staylime.com/docs/volume-themes/changelog/volume-release-notes.md).

Keep the old theme in your library for a week or two. It is the fastest rollback you have: publishing it again restores the previous storefront instantly.

***

### If something is wrong after updating

Write to us with your store URL, the theme name and version, and what differs from before. We can look at the theme itself — for customizations added by another developer we can quote the work, but they are outside free support.

***

### Related

* [How to use the Shopify theme editor](https://staylime.com/docs/getting-started/how-to-use-the-shopify-theme-editor.md)
* [Shopify Canvas vs the standard theme editor](https://staylime.com/docs/getting-started/shopify-canvas-vs-the-standard-theme-editor.md)
* [Troubleshooting guide](https://staylime.com/docs/theme-management/troubleshooting-guide.md)
* [Updating themes — Shopify Help Center](https://help.shopify.com/en/manual/online-store/themes/managing-themes/updating-themes)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://staylime.com/docs/theme-management/how-to-update-your-shopify-theme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
