How to Upgrade a Shopify Theme Without Losing Custom Code

Updating a Shopify theme is not clicking “add latest version” and publishing it. The new theme contains vendor improvements and platform compatibility, while the live theme may contain years of sections, settings, app blocks, analytics, accessibility fixes, and business logic. Replacing one with the other can silently remove features; copying every old file can erase the upgrade.

Treat the work as a three-way merge between the old vendor base, the customized live version, and the new vendor release. The goal is to carry intentional merchant changes forward while adopting the new theme architecture wherever possible.

Decide why the upgrade is needed

Write the reason and measurable outcome: support a new Shopify feature, obtain bug or accessibility fixes, improve performance, resolve app compatibility, refresh design, or return to a maintainable vendor path. An upgrade should not become an unbounded redesign unless that scope is explicit.

Read the theme vendor’s release notes and support policy. Identify breaking changes, renamed settings, changed sections, deprecated snippets, new dependencies, and migration tooling. Confirm the license permits the target store and that the downloaded version is authentic.

If the existing theme is extremely old or heavily rewritten, a rebuild onto the new base may be safer than line-by-line merging. Make that decision after inventory, not from file count alone.

Create recoverable backups and version control

Duplicate the live theme in Shopify and download/pull its files. Export the live theme identifier, settings, templates, navigation references, markets, redirects, and app configuration relevant to the storefront. Preserve screenshots and videos of important interactions.

Put the old base, current customized theme, and new base in Git. If you do not have the exact old vendor version, obtain it from the vendor or history where possible. Without the ancestor, every vendor line can look like merchant customization.

Use branches and focused commits. Never experiment directly on the live theme. Keep the previous live theme unpublished after release as a visual rollback, while remembering external app/data changes need their own rollback.

Inventory every customization

Search Git history, project notes, theme code, app embeds, and stakeholder knowledge. Build a register with feature, business owner, templates, files, settings, dependencies, data fields, app/API, analytics events, last change, test case, and decision.

Classify:

• visual branding and design tokens;
• custom sections, blocks, snippets, and templates;
• product, variant, bundle, subscription, and cart logic;
• navigation, search, filters, localization, and Markets behavior;
• app blocks, embeds, scripts, pixels, and proxies;
• metafields, metaobjects, tags, and naming conventions;
• SEO metadata, canonical, structured data, robots, and redirects;
• accessibility and performance fixes;
• analytics and consent;
• code that appears unused or belongs to removed apps.

Unknown code should be investigated, not copied automatically. This inventory is also the chance to retire app leftovers and obsolete experiments using the safe process in our app-bloat guide.

Capture a behavioral baseline

Create a representative test matrix: home, primary collections, search, products with different media/options/states, cart, account, blog, contact, policies, markets, and languages. Include sold out, sale, gift card, subscription, bundle, long title, no image, and high variant counts.

Record screenshots at mobile, tablet, and desktop widths. Test keyboard, focus, screen-reader labels, reduced motion, zoom, and color contrast. Capture LCP, INP diagnostics, CLS, network requests, and console errors. Record GA4 and ad events through purchase.

Place test orders with major payment, shipping, tax, discount, currency, and consent scenarios. A theme is commerce software; visual similarity alone is not acceptance.

Compare the three versions

The old vendor base versus the live theme reveals merchant changes. The old base versus the new base reveals vendor changes. Review both before applying code.

For each customization choose:

1. Carry forward: still required and compatible.
2. Reimplement: required, but new architecture offers a better integration point.
3. Replace: new vendor or Shopify feature covers it.
4. Retire: no longer used or justified.

Do not overwrite new theme.liquid, global JavaScript, CSS, or section groups with old copies. That discards the release’s structural work. Port the smallest intentional change into the new code and follow current conventions.

Review current local Next or Shopify docs where applicable; platform conventions change. For themes, run Shopify Theme Check and heed deprecations rather than preserving obsolete Liquid because it still renders today.

Migrate settings intentionally

settings_data.json holds merchant configuration and references section/block settings. Copying it blindly can introduce settings that no longer exist or omit new defaults. Compare settings_schema.json, setting IDs, types, defaults, and presets.

Map global colors, typography, layout, social links, favicon, cart behavior, search, product card, and custom settings. When IDs changed, translate values. Remove stale app blocks only after confirming the app is retired.

JSON templates and section groups require equal care. Compare section types, block IDs, order, disabled state, and settings. Rebuild templates using new vendor sections when they replace old custom code. Keep a machine-readable mapping and manually inspect the result in the editor.

Port custom sections and snippets

For every custom section, verify schema validity, unique setting IDs, defaults, localization, dynamic sources, app-block support, limits, presets, and accessibility. Update Liquid syntax and image handling to current best practices.

Avoid carrying an entire old vendor section merely because two lines were customized. Reapply the change to the new section or expose a setting. Extract merchant-specific functionality into clearly named snippets/assets so the next upgrade has a smaller diff.

Use responsive images with Shopify filters, intrinsic dimensions, and appropriate loading. Keep critical content in HTML and progressively enhance. Ensure JavaScript initializes once in the theme editor and when sections load dynamically.

Reconnect apps through supported extensions

Open the new theme in the editor and verify every app embed and block. Blocks in the old JSON template may not exist in the new theme automatically. Re-add them through supported interfaces and reproduce settings.

Prefer theme app extensions over manually pasted vendor snippets when the app supports them. Ask vendors for current installation instructions. Check subscription, reviews, bundles, search, personalization, loyalty, chat, consent, and analytics on all affected templates.

Do not copy old app code “just in case.” It can duplicate the extension, load stale endpoints, or break uninstall behavior.

Preserve SEO signals

Compare rendered title, meta description, canonical, robots, hreflang, Open Graph, Twitter metadata, Product/Article/Breadcrumb structured data, headings, content, links, image alt text, pagination, and status behavior.

Theme upgrades can accidentally output two canonical tags, remove collection copy, change product URL links, duplicate H1s, or replace structured data with incomplete vendor defaults. Crawl both preview versions and diff results by template.

Keep public URLs unchanged unless a separate migration is planned. If URLs change, create direct redirects and update internal links. Confirm no preview hostname appears in canonicals or social images. Use our technical SEO audit as the acceptance framework.

Preserve analytics and consent

Inventory Google channel, GTM, custom pixels, app pixels, theme data layer, Meta/TikTok, affiliate, consent, and event listeners. Determine which are theme-dependent.

Test product/list views, add-to-cart from every interface, cart changes, checkout, purchase, and consent states. Ensure the new theme does not fire both old custom code and app extension. Use stable item and transaction IDs and reconcile a test order. See our GA4 guide.

Never paste a production secret into a public theme asset. Keep supported pixels and protected server operations in appropriate systems.

Test performance and accessibility as regressions

Compare the same URLs, devices, network profiles, and test runs. Identify the actual LCP element, long interaction tasks, layout shifts, JavaScript transfer, third-party requests, and image behavior. A new theme can be faster by default but slower after old code is copied.

Set budgets for critical JavaScript, image weight, third-party requests, and layout shifts. Test menus, modals, drawers, sliders, filters, variants, cart, forms, and theme-editor reload. Ensure focus is trapped/restored correctly, escape closes dialogs, labels exist, and motion preferences are respected.

Performance and accessibility fixes from the live theme must be evaluated against the new base: some should be carried forward; some are already solved differently by the vendor.

Use staged acceptance

Run automated Theme Check, lint/build processes for custom assets, link/crawl checks, structured-data validation, and visual regression. Then use human testing.

Organize acceptance by owner:

• merchandising validates templates and editor controls;
• marketing validates campaigns, content, pixels, and SEO;
• operations validates order, inventory, fulfillment, notification, and returns;
• support validates account and common customer issues;
• finance validates tax, discount, payment, and reporting;
• development validates code, performance, accessibility, errors, and rollback.

Track every defect with severity, template, steps, expected/actual result, owner, and retest evidence. Do not approve from a homepage screenshot.

Prepare the release runbook

Freeze theme edits or define a final delta process. Note changes made to the live theme during development and merge them before release. Schedule a quiet window with decision-makers available.

The runbook should include final backup, theme ID, commit, app settings, content freeze, test order, publish action, smoke checks, analytics annotation, monitoring dashboards, rollback trigger, and owner. Avoid simultaneous app, domain, checkout, and campaign changes.

After publish, verify home, collection, product, search, cart, account, language/market, contact, and policy pages. Place a real order, confirm analytics and notifications, inspect console and errors, and monitor conversion.

Maintain an upgrade ledger

After release, document new theme version, vendor notes, carried/rebuilt/replaced/retired customizations, files and extension points, settings mapping, tests, known limitations, and next review date. Tag the release in Git.

Adopt a customization policy: prefer theme settings, isolated sections/snippets, supported app extensions, minimal global patches, clear naming, and tests. Review vendor releases regularly so upgrades remain incremental instead of becoming a multi-year rescue.

Theme upgrade checklist

• Old base, customized live theme, and new base are preserved in Git.
• Customization inventory has owners and decisions.
• Behavioral, visual, performance, SEO, analytics, and accessibility baselines exist.
• Changes are reimplemented on the new base rather than overwriting it.
• Global settings, JSON templates, and section groups are mapped.
• Apps use current supported blocks/embeds/extensions.
• Product, cart, checkout, Markets, and edge states pass.
• Canonical, schema, links, hreflang, and public URLs remain correct.
• Analytics, consent, and purchase reconcile.
• Release has freeze, smoke tests, monitoring, and rollback.
• Upgrade ledger reduces the next merge.

If your live theme is too customized to update confidently, contact Shopimaster. We can reconstruct the change history, merge custom functionality onto the current vendor base, remove obsolete code, run commerce and SEO regressions, and release with a documented rollback.

Before closing the project, compare the first full week with the saved baseline. Review product-template errors, add-to-cart success, checkout completion, organic landing behavior, search usage, app alerts, and support contacts. Interview the staff who edit the theme: technical acceptance is incomplete if routine merchandising has become slower or confusing. Record any deferred improvement with an owner and target release rather than leaving it in chat history. Finally, archive the tested theme package and dependency versions alongside the release notes, so an emergency investigation can reproduce exactly what customers received.