To update our customized Shopify Horizon theme without losing code changes, we combined Shopify's official update draft, Git history, and a Codex-assisted three-way audit—then verified the result through storefront QA.
CheckoutWorks runs on Shopify, and our own storefront uses Horizon. Our update from 4.1.4 to 4.1.5 became the first full test of this workflow: what Shopify transferred, what Codex helped us migrate, what QA still caught, and what we will repeat next time.
Why we keep our Horizon theme current
Shopify theme updates can include new features, design improvements, and bug fixes. Some newer features also depend on updated theme architecture, so an existing theme does not automatically gain everything Shopify releases.
Shopify describes Horizon as its flagship first-party theme, built around current Liquid storefront features. Staying reasonably current lets our own site benefit from Shopify's ongoing work without giving up the parts of the storefront we have deliberately customized.
The trade-off is simple: every custom edit can make the next update harder. Our goal is therefore not zero custom code. It is custom code that is easy to identify, review, test, and carry forward.
How we make our customizations easier to carry forward
For our own theme, we follow a native-first order:
- Use a native Shopify or Horizon feature when it meets the requirement, such as the dynamic sources behind our storefront FAQs built from metaobjects.
- Use Theme Editor settings or Custom Liquid for small, modular additions, such as our country-aware size chart or a link that opens the Shopify Inbox chat.
- Add custom theme code only when the native options are not enough, such as our variant button badges, which live in one snippet with two small render calls in Horizon's files, or our block that hides content on mobile or desktop, which is a single new theme block file with no edits to Horizon's own files.
When custom code is necessary, we try to keep related changes together. Store-specific CSS lives in a dedicated stylesheet where practical. Modified Liquid and CSS regions include a nearby Modified by CheckoutWorks.dev comment. Git records the history behind each change, including older work that predates the comment convention.
These habits do not make an update automatic. They make the evidence easier for both a developer and Codex to inspect.
Write edits the updater can carry
Shopify's updater includes your code edits in the new draft when they do not conflict with the new version. Our later update from 4.2.0 to 4.3.0 added the draft with a warning that our code edits could not be included, and gave this reason:
Rebase failed with conflicts: ["snippets/product-media-gallery-content.liquid"]
One of our customizations had rewritten lines in that snippet, and 4.3.0 changed the same lines. We moved our customizations into a fresh copy of 4.3.0 using the inventory and reapply steps below, then changed three habits so the next update has less to conflict with:
- Add lines instead of rewriting them. Our color image grouping used to replace Horizon's media sorting. It is now one block placed after that sorting, and every original line stays in place.
- Override CSS from the dedicated stylesheet. Four Horizon files held only style changes of ours. Those overrides now live in our stylesheet, and the four files match the original theme again. An override depends on the theme's selector, so a theme change can make it stop applying without an error. Check those styles by eye after each update.
- Use public theme blocks for custom blocks. A private block, whose file name starts with an underscore, must be named in a section file that belongs to the theme. A public block needs no entry there, so the section file stays original. This also avoids the "Block type is not allowed" update error.
These changes reduced the Horizon files that carry our edits from 29 to 24. The edits that remain are small, marked changes inside Horizon's own code, and an update can still conflict with them.
Step 1: Start with Shopify's official theme update
We first used the update offered in Shopify Admin. Shopify's documented process adds the new version as a draft, so the live storefront remains unchanged while the update is reviewed. Theme Editor settings, layouts, section and block settings, templates, app embeds, and theme-content wording are copied to the updated theme. Non-conflicting code edits can also be included. When an edit does conflict, the draft is still added, with a warning that code edits could not be included.
If the update stops before a draft is created, with a message that the updated copy could not be added to the Theme Library, clear the validation error in the old theme and run the update again.
We treated JSON templates and config/settings_data.json separately as Theme Editor state rather than ordinary code edits, as described in Step 4.
Shopify offered Horizon 4.1.5 as an update to our 4.1.4 theme.
This official draft is the right starting point because it preserves the new theme's structure. Copying old files wholesale into it could silently replace official fixes or newer implementations with older code.
The existing live theme stayed active while the 4.1.5 update remained a separate draft.
Step 2: Keep the update states separate
Before migrating code, we preserved distinct reference points:
- The current live theme.
- The untouched Shopify-generated update draft.
- A working QA copy of the updated theme.
- The previous live theme as a rollback option.
- Git history and local theme snapshots for detailed comparison.
The exact names matter less than making each role obvious. A name such as Horizon 4.1.5 — Shopify Update Baseline should never be confused with Horizon 4.1.5 — QA or the current live theme.
We keep the current live version, the untouched update baseline, the QA draft, and the previous live rollback until the new theme has been published and monitored. Older development drafts do not need to stay in Shopify forever when their history is safely preserved in Git.
When this level of review is useful
For an almost-unmodified Horizon theme, Shopify's built-in updater may be enough. The three-way workflow becomes more useful when the live theme contains custom Liquid, CSS, JavaScript, app-generated code, or older changes that were never documented.
Step 3: Let Codex build the customization inventory
Codex is not required to update Horizon. We used it to speed up the audit and migration of our existing customizations. Before editing anything, we asked Codex to plan a three-way review rather than make a simple "old versus new" comparison:
- The original, unmodified Horizon 4.1.4 baseline.
- Our customized CheckoutWorks Horizon 4.1.4 live theme.
- The Shopify-generated Horizon 4.1.5 draft.
The initial Codex plan separated the official baseline, the customized theme, and the new target.
The audit identified 15 code files that needed detailed review. Thirteen already had our customization marker. Two more had no marker, but Git history confirmed that they contained store-specific work. Codex also found three standalone custom files that Shopify's update had already preserved, so they did not need to be copied again.
The audit grouped custom code, Theme Editor data, content changes, and official Horizon changes separately.
This inventory prevented two common mistakes: missing an old customization because it lacked a comment, and reapplying a customization that Shopify had already transferred.
Find your customizations without Codex or Git
The same inventory can be built by hand. It takes two comparisons, because customizations live in two places.
Code files. Download your current theme from Online Store > Themes, and get a clean copy of the same version. For Horizon, each release is a commit in Shopify's GitHub repository titled with its version number. Compare the two folders with a file comparison tool. Every Liquid, CSS, or JavaScript file that differs holds a customization, and every file that exists only in your theme was added by you or an app.
Theme Editor data. Some customizations are saved as settings and never appear as a code edit. Search the JSON files in your theme's templates and sections folders for these three strings:
-
custom-liquidfinds Custom Liquid sections and blocks. -
custom_cssfinds CSS added in a section's Custom CSS field. -
shopify://appsfinds app blocks, including blocks left by apps you have uninstalled.
Then compare the default language file in the locales folder, such as en.default.json, to find wording you changed.
Step 4: Migrate the intent, not the old files
For every customization, we asked what behavior it was meant to preserve. Then we reapplied that behavior to Horizon 4.1.5 using the new version's structure.
Small, isolated changes could be moved directly. Files that Shopify had changed substantially needed a new implementation. JSON templates and settings_data.json were reviewed as Theme Editor state rather than overwritten as complete files.
Nearby attribution comments make custom regions easier to locate during the next update.
We also had Codex generate or restore comments around modified code regions. Comments are not a replacement for Git, but they provide an immediate signal when someone opens a theme file months later.
Why we chose the three-way audit
| Approach | What it preserves | Main trade-off |
|---|---|---|
| Copy old theme files over the update | Old custom code | Can replace newer Horizon fixes or architecture with older code |
| Use Shopify's official update only | Official changes plus transferable settings and code | Conflicts and undocumented edits can still be missed |
| Use the official draft with Git and a Codex three-way audit | Official changes plus reviewed customizations | More QA, but it gave us the clearest migration path |
Step 5: What the code audit missed
A clean code comparison is not proof that the storefront still looks and behaves correctly. Our QA found a button font-weight customization that existed in the live theme but was absent from the new draft. It was older than our reliable marker convention, so a comment-only audit could have missed it.
Before: The updated draft used the lighter default button weight.
After: The intended heading weight was restored and rechecked.
This was a useful reminder: AI can trace files and history quickly, but visual QA catches behavior that code metadata cannot fully describe.
If you notice something missing only after an update is live, our guide to finding and restoring customizations lost in a Shopify theme update covers where to look and how to bring each one back.
Step 6: Validate before publishing
We ran Shopify Theme Check across the completed theme. It inspected 366 files and returned zero errors. Two known OrphanedSnippet warnings remained for snippets called dynamically through Custom Liquid. Static analysis cannot see those runtime references, so we verified both snippets in the storefront instead of deleting them.
Theme Check completed with zero errors and two understood warnings.
We also reviewed the main storefront routes on desktop and mobile, tested key product and cart interactions, opened the Theme Editor, and checked that sections and blocks could still be saved. Custom CSS selectors received extra attention because selectors from an older theme version might no longer exist after an update.
Step 7: Publish with a rollback path
Only after the code audit, visual review, interaction testing, and Theme Check did the 4.1.5 draft become the new active theme. The previous live theme stayed available as a short-term rollback, while Git retained the durable history.
Horizon 4.1.5 became active after the migration and QA were complete.
Theme update checklist: before and after
This is the short version of the workflow, with the checks our Horizon updates so far showed we needed. It applies to any Shopify theme.
Before you add the update
- Capture the current storefront. Take desktop and mobile screenshots of the home page, one product for each product template, a collection, the cart, search results, and a page with a form.
- Download the theme. Keep a copy outside Shopify, or commit the current state to Git.
- List your customizations. Use the inventory steps above, and note your custom templates and which pages use them.
- Note the active app embeds. Each theme keeps its own app embed settings.
- Remove blocks from uninstalled apps. In the theme editor, open each template and delete any block marked with a red warning icon.
- Check connections to deleted metafields. If you have deleted metafield definitions, remove the blocks or settings that were connected to them.
The last two can stop an update before a draft is created.
Before you publish the updated draft
- Read the status line in the theme library. "Code edits successfully included" and "code edits could not be included" lead to different amounts of work. The second can list the files that conflicted; start with those.
- Compare pages with your screenshots. Check desktop and mobile. Look at colors, fonts, button styles, and spacing as well as layout.
- Compare the wording. Check cart, form, and button text against the old theme. Custom text was the only thing our 4.1.5 to 4.2.0 update dropped.
- Test the buying path. Select variants, add to cart, change the quantity, open the cart, and continue to checkout.
- Check template assignments. Open one page or product for each custom template.
- Check apps. Compare App embeds with the old theme, and load the pages where app blocks appear.
- Save in the theme editor. Open the draft, change one setting, and confirm it saves without an error.
- Check colors on a major update. Moving from Horizon 3.x to 4.x changes how text colors are chosen.
After you publish, keep the previous theme in your library for a few days, so you can roll back by publishing it again.
What we will repeat with every Horizon update
- Prefer native Shopify features and keep custom code focused.
- Mark custom code regions and preserve history in Git.
- Add code beside Horizon's code instead of rewriting it.
- Use Shopify's official update to create the new draft.
- Keep the live theme, update baseline, QA draft, and rollback copy distinct.
- Use Codex to inventory changes with comments, Git history, and three-way comparison.
- Reapply customization intent without overwriting the new theme's foundation.
- Run Theme Check and test the actual storefront and Theme Editor.
- Publish only after the new draft passes QA.
The main lesson was that Codex worked best as an audit and implementation partner, not as a one-click updater. Shopify supplied the new foundation. Git supplied the history. Codex helped us connect the evidence and reapply the intended behavior. Storefront QA decided whether the result was actually ready.
That combination gives us a practical way to keep our own Horizon theme updated while retaining the storefront details we intentionally built. The next release should begin with a cleaner inventory, clearer markers, and fewer surprises than this one.