> 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-companion/theme-updates/shopify-built-in-updates.md).

# Theme Companion and Shopify's built-in updates

### How Shopify's built-in update works

When a new version of a Theme Store theme is released, Shopify lets you add an updated copy to your draft themes. Customizations made in the **Theme Editor** — settings, layouts, section and block settings, new templates — are always carried over.

Code edits are a different story. If you (or an app) edited theme code, Shopify includes those edits only when they don't conflict with the update. If they do, the theme is added with the message *"code edits could not be included"* — and it's up to you to find your edits and copy them into the new version by hand. Shopify's documentation suggests using a diff app to identify what you changed.

<figure><img src="https://1681854268-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUyDyU30RpMsjQtm2Gbnm%2Fuploads%2FVBiOqusdXxLOulJfrV9z%2FScreenshot%202026-08-19%20at%2016.25.53.png?alt=media&#x26;token=27d525b4-365a-42cc-b80a-8cd3a6e626e5" alt=""><figcaption></figcaption></figure>

So the built-in update works well right up to the moment your code edits and the new version touch the same code — and that's exactly where it stops helping.

### What Theme Companion does differently

Theme Companion is built for that moment. Instead of dropping your code edits when they conflict, it merges your theme with the new version file by file and turns every overlap into a **conflict** you decide explicitly. That changes three things:

* **Conflicts are decided, not dropped.** The built-in update stops at *"code edits could not be included"* and leaves you to find and re-apply your changes by hand. In Theme Companion, everything that doesn't conflict is still carried over — and each conflict is shown to you with both sides visible.
* **You can combine both changes.** For each conflict: keep yours, take the new version's, or edit and merge them — keeping your customization *and* the vendor's improvement. That third outcome doesn't exist in the built-in update at all.
* **Nothing is dropped silently.** Every edit is either carried over or shown to you as a decision, and you confirm the final result — the guarantee the built-in update can't make.

**What this doesn't mean:** it doesn't make every decision effortless. A conflict exists because you and the theme vendor changed the same code in different ways — no tool can know which result you want. Most conflicts resolve with a click; a few need a closer look. The hardest cases come from distance: while you keep customizing your theme, the vendor keeps releasing new versions — often monthly. The longer updates are postponed, the further the two sides drift apart, and some customizations may eventually need to be re-applied in the new version's structure. See [When conflicts get hard](/docs/theme-companion/theme-updates/when-conflicts-get-hard.md) — and keep in mind that in every one of those cases, the built-in update would simply have left your edits behind.

**At a glance:**

<table><thead><tr><th width="272.078125">Scenario</th><th>Shopify's built-in update</th><th>Theme Companion</th></tr></thead><tbody><tr><td>Theme Editor customizations (settings, layouts, templates)</td><td>Carried over</td><td>Carried over — never rewritten</td></tr><tr><td>Code edits that don't conflict</td><td>Carried over</td><td>Carried over</td></tr><tr><td>Code edits that conflict</td><td>Not included — you re-apply them by hand</td><td>Shown as conflicts you decide, side by side</td></tr><tr><td>Keeping your edit <em>and</em> the vendor's change in one place</td><td>Not possible</td><td>Edit and merge them in the conflict</td></tr></tbody></table>

### After you update with Theme Companion

A theme created by Theme Companion is technically an *uploaded* theme, and Shopify treats all uploaded themes the same way:

* The theme card in your Online Store no longer shows update notifications for new versions.
* [Shopify's automated updates](https://help.shopify.com/en/manual/online-store/themes/managing-themes/updating-themes#automated-updates-for-your-theme) no longer apply to this theme.

This is a Shopify platform rule for all uploaded themes, not something an app can change. In practice it changes one habit: **your next updates come from Theme Companion, not from the Online Store.** Open the app to see when a new version is available and run the update from there.

And nothing is lost in the trade: for a customized theme, the built-in update was never the safe path — it carries code edits only while they don't conflict. Theme Companion carries your customizations through every update, and shows you anything that needs a decision.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://staylime.com/docs/theme-companion/theme-updates/shopify-built-in-updates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.