How to Migrate a Vintage Shopify Theme to Online Store 2.0

Why this migration is different from a theme update

Plenty of stores still run vintage Shopify themes: Liquid-only templates where only the home page supports sections, and where apps inject their code directly into theme files. Shopify’s developer documentation is clear that upgrading to Online Store 2.0 “isn’t mandatory” — vintage themes keep working — but the platform’s feature development has moved on. JSON templates, sections on most page types, app blocks, and dynamic metafield sources all assume the newer architecture.

The migration itself is not a version bump you click through in the admin. It is a structural conversion: Liquid templates become JSON template files, and the markup that used to live in those templates moves into section files that the JSON references. You can convert one template at a time or the whole theme, but either way someone has to touch code.

This guide walks through the decision first, because the honest answer to “should we migrate?” is sometimes “no”, and then the conversion itself.

Step 1: Decide whether to migrate, rebuild, or do nothing

Shopify’s migration assessment documentation frames the decision around five factors: whether you actually need OS 2.0 features, whether you’re satisfied with the current design, how heavily the theme is customized and how many apps it relies on, your budget, and your team’s comfort with code. Those factors sort into four realistic paths:

• Do nothing. If the store doesn’t need sections on non-home pages, app blocks, or metafield-driven content, and the current theme performs well, staying put is a legitimate choice. Vintage themes remain supported.
• Install a different theme. When the merchant is tired of the current design, customizations are light, and there’s budget (or a suitable free theme in the Theme Store works), buying into a modern theme is faster than converting an old one.
• Update the current theme. If the theme came from a third-party developer who ships an OS 2.0 version, take theirs. You get the new architecture plus their ongoing maintenance, which matters for security and platform updates.
• Migrate manually. Bespoke themes, heavily customized ones, and stores where the design is the brand generally justify a manual conversion. That’s the path the rest of this article covers.

One warning before you commit: app-made and manual customizations cannot be migrated automatically. Budget time to reinstall apps and reapply custom work after the theme structure changes.

Step 2: Audit what’s actually in the theme

Before converting anything, take inventory of the starting point:

1. List every template and its purpose. Look in the templates/ directory. Note which ones are customized beyond Shopify’s originals and which page types each serves, including alternate templates like product.wholesale.liquid.
2. Diff against the original theme. If you started from a Theme Store theme, download the original version and compare. This tells you how much of the conversion is “rebuild what the original did” versus “port custom work.”
3. Check your apps. For each installed app, confirm whether it offers app blocks (theme app extension based) or still writes into theme files. This is also the moment to deal with ghost code from previously uninstalled apps — the audit workflow in our guide to removing leftover app code belongs here, because you do not want dead snippets migrating forward into a freshly converted theme.
4. Record current settings. Screenshot the theme settings panel and note anything a merchant has configured, so you can verify nothing visibly regresses after the switch.

Work on a duplicate of the theme, never the live copy. Every plan in this article assumes the published theme stays untouched until the replacement is validated.

Step 3: Convert your first Liquid template to JSON

Online Store 2.0’s core mechanic is the JSON template: a data file in templates/ that declares which sections render on the page, in what order, and with what settings. The structure is small:

{
  "sections": {
    "main": {
      "type": "product",
      "settings": {
        "show_vendor": true
      }
    },
    "recommendations": {
      "type": "product-recommendations"
    }
  },
  "order": ["main", "recommendations"]
}

Three rules from Shopify’s JSON template documentation govern the conversion:

• A template exists as either Liquid or JSON, never both. If product.liquid exists, you cannot create product.json. The conversion is a replacement: delete the Liquid file, create the JSON file with the same base name.
• Every entry in sections points to a section file. The type value is the filename of a section in sections/ without the extension — "type": "product" renders sections/product.liquid.
• order lists section IDs in render order. IDs must be unique, and a template can reference up to 25 sections (with up to 50 blocks per section).

The practical unit of work is the companion section. For each page type you convert, you build a section that carries the core functionality the old Liquid template provided — typically named main in the JSON, wrapping the page’s primary content. The markup from the old template body moves into that section. Static content that used to be hardcoded into the template can either stay hardcoded in the section or, better, become section settings so merchants gain editor control over it.

Start with a low-risk template, not the product page. A simple page like list-collections or a static page template is a good first conversion: it exercises the JSON structure, section referencing, and editor behavior without touching the buying flow.

Step 4: Make sections manageable in the theme editor

Converting the file format is half the job. The other half is making the result behave the way merchants expect from an OS 2.0 theme.

Add presets so sections appear in the editor. A section only shows up as “addable” in the theme editor if its schema defines presets. Sections without presets can still be referenced from the JSON template directly, but a merchant can’t add them to other pages or remove them in the editor. Since editor flexibility is usually the reason for migrating, most sections you port should get presets with sensible default settings.

Split monolithic templates into logical sections. A vintage product template is often one long file: gallery, buy box, description, reviews include, related products. Ported as a single section, it works — but you’ve gained file structure without gaining flexibility. Splitting it into separate sections (gallery, buy buttons, description, recommendations) is what actually lets merchants reorder and toggle page components, which is the payoff of the migration.

Check enabled_on and disabled_on. Section schemas can restrict which templates a section is available in. Set these deliberately so merchants don’t accidentally add a product-only section to a blog page and produce broken output.

Use dynamic sources where they earn their keep. JSON template sections can connect settings to object attributes and metafields. This is worth doing for content your merchandising team changes often — size guides, care instructions, delivery notes — but it’s not an all-or-nothing requirement. Convert the obvious cases and leave the rest for later.

Step 5: Handle apps and custom integrations

After the structural conversion, reinstall apps one at a time. Apps built on theme app extensions install their blocks through the theme editor, leave no code in your files, and remove themselves cleanly on uninstall — the architecture Shopify designed specifically to eliminate the ghost-code problem. Apps that still modify theme files should be treated as candidates for replacement, because they will reintroduce exactly the maintenance problems this migration is meant to end.

Custom integrations that wrote into theme files — analytics snippets, third-party widgets, hand-rolled schema markup — need porting into the new section structure. Do them last, one by one, verifying each renders correctly, so a broken integration doesn’t hide inside a larger diff.

Step 6: Validate, then switch over

Before publishing:

1. Walk every converted template in the theme editor. Add, remove, and reorder sections. If a section can’t be added, check for a missing preset. If the editor errors, it usually means a JSON type references a section file that doesn’t exist.
2. Compare rendered output. View pages from the duplicated theme and the live theme side by side — product, collection, cart, blog, and any alternate templates. Watch for lost settings, missing sections, and layout regressions.
3. Re-check performance. A migration is a natural checkpoint for a baseline: measure the new theme before it goes live using the method in our Shopify theme performance guide, so you know the rebuilt sections didn’t quietly regress anything.
4. Publish the new theme as the live theme, keep the old one installed for a rollback window, and remove it only after a week or two of stable operation.

When to hand this off

A manual migration is realistic for a developer comfortable with Liquid, HTML, CSS and JavaScript — that’s the skill set Shopify’s own documentation prescribes for it. If the theme is bespoke, the sections need genuine redesign rather than mechanical porting, or the store is revenue-critical and downtime is expensive, the work scales up quickly. Our Shopify development service handles theme conversions, section refactoring and app cleanup, and the Shopify platform page describes how we maintain that stack generally.

The same assessment logic — upgrade in place, replace, or rebuild — also shows up outside Shopify. If this exercise has you questioning the platform itself rather than just the theme, the decision framework in our article on page builders versus custom themes covers the trade-offs between editor flexibility and bespoke code, which is precisely the question Online Store 2.0 answers with “both, if you structure it well”.