Shopify 2.0 migration: what actually breaks

I've done around ten Online Store 2.0 migrations in the past year. This is the summary of what actually breaks, sorted by how painful the fix is.

The easy stuff

Most theme migrations start smoothly. You duplicate the theme, run the migration wizard, and 70% of your sections convert cleanly. The header, footer, hero, and product templates almost always come through in one piece.

Don't get comfortable. The hard part is what the wizard doesn't tell you.

What the wizard doesn't catch

Third-party app blocks. Apps that injected themselves into your theme via snippets don't automatically become app blocks. They stay as raw Liquid. You have to replace them by hand, if the app even supports a 2.0 block. Many don't. Some do but only in their paid tier.

Custom metafields. If you were using metafields via string matching in Liquid (product.metafields["namespace"]["key"]), you need to redefine them as definitions in the admin so they show up in the new theme editor. The old references will keep working, but you lose the editor integration.

Sectioned pages vs static pages. Your old page.liquid was one template. In 2.0, you can have different layouts per page. Great in theory. In practice, it means every marketing page you'd built with raw HTML blocks needs to be rebuilt as sections, or the content editor won't be able to touch it anymore.

What's worse than the docs suggest

Asset paths. The new theme structure changes where certain files live. If you had hardcoded asset URLs anywhere in your HTML (product descriptions, blog posts, metafields), they'll break. Search your shop for cdn.shopify.com references before you migrate, not after.

Layout regression. The new themes ship with different default styles. Padding, margins, font sizes, even line heights can shift by a few pixels. On a carefully designed page, "a few pixels" means "the hero image now overlaps the button." Budget a day for visual QA.

Checkout scripts. If you had custom scripts in checkout.liquid (Shopify Plus only), 2.0 doesn't change that, but the migration process is a good time to check that they still work. I've seen scripts that were quietly broken for months because nobody noticed.

What you'll regret skipping

Taking a full backup of the old theme before you start. I know, Shopify keeps unpublished themes around. I've still seen stores lose work because someone deleted the old theme three weeks in to "clean up the theme list."

Testing in a staging environment that matches production data. Synthetic data misses edge cases: products with 60+ variants, customers with long shipping addresses, orders with 40 line items. Always test with real data copies.

Writing down what you changed. During a migration, you'll touch dozens of small things. Six months later, when something breaks and you're trying to remember if you edited that snippet on purpose, you'll wish you had notes.

The honest recommendation

If your store does more than $50k/month, don't do this yourself. Not because you can't, but because the opportunity cost of an extra week of downtime or a subtle regression is way higher than what a proper migration costs.

If you're under that threshold and you have the time, go for it, but block off at least two weeks and expect to find one or two gnarly issues per week.

Either way: if something breaks mid-migration and you're stuck, book a call and let's unstick it.