Skip to main content

​
Overview

This guide helps you safely migrate your Horizon theme to the latest version while preserving your customizations and store settings.
Always test theme updates on a development or staging store before applying them to your live production store.

​
Before You Begin

1

Backup your current theme

Download a copy of your current theme from the Shopify admin:
  1. Navigate to Online Store > Themes
  2. Find your current theme
  3. Click Actions > Download theme file
  4. Save the .zip file in a safe location
2

Review the release notes

Check the release notes to understand what’s changed in the new version and identify potential breaking changes.
3

Prepare a test environment

Create a duplicate of your store or use a development store to test the migration before applying it to production.

​
Migration Methods

​
Method 1: Pulling Upstream Changes (Recommended)

If you’re using Git to manage your theme, you can pull the latest changes from the Horizon repository.
1

Navigate to your local theme folder

2

Verify your remotes

Check that you have both origin and upstream configured:
You should see:
  • origin - your repository
  • upstream - Shopify’s Horizon repository
3

Add upstream remote if needed

If you don’t see an upstream remote, add one pointing to Shopify’s Horizon repository:
4

Fetch and pull the latest changes

This may result in merge conflicts if you’ve modified core theme files. You’ll need to resolve these conflicts manually.
5

Resolve merge conflicts

If you encounter conflicts:
  1. Open each conflicted file in your code editor
  2. Look for conflict markers (<<<<<<<, =======, >>>>>>>)
  3. Decide which changes to keep (yours, upstream, or both)
  4. Remove the conflict markers
  5. Test the resolved code

​
Method 2: Manual File Comparison

For smaller updates or if you’re not using Git:
1

Download the latest Horizon release

2

Compare settings files

Use a diff tool to compare:
  • config/settings_schema.json
  • config/settings_data.json (your customizations)
  • Section schema files in sections/
3

Update modified files

Carefully copy updates from new files to your theme, preserving your customizations.
4

Test thoroughly

Test all pages and functionality before deploying.

​
Version-Specific Migration Notes

​
Migrating to v3.4.0

The account menu has been replaced with a new web component version.Action required:
  • Test all customer account functionality
  • Verify login, logout, and account navigation work correctly
  • Check that any custom account-related CSS still applies
New settings allow control over product card widths on desktop and mobile.Action required:
  • Review product grids on collection pages
  • Adjust new width settings in section configurations if needed
  • Test responsive behavior on various screen sizes
Footer and header elements now use proper semantic HTML and ARIA roles.Action required:
  • If you’ve customized header or footer markup, update to use semantic elements
  • Test with screen readers to ensure accessibility is maintained

​
Post-Migration Checklist

After updating, verify the following:
  • Homepage loads correctly
  • Collection pages display products properly
  • Product pages show all variants and media
  • Cart and checkout flow works
  • Search functionality operates correctly
  • Customer account login/logout works
  • Mobile navigation functions properly
  • Color schemes are correct
  • Typography matches your brand
  • Logo displays at the right size
  • Images load with correct sizing
  • Spacing and layout look appropriate
  • Custom CSS is still applied
  • Page load times are acceptable
  • Images are optimized and loading
  • No console errors in browser DevTools
  • Theme Check passes without critical errors
  • Chrome/Edge (Chromium)
  • Firefox
  • Safari (macOS and iOS)
  • Mobile browsers (iOS Safari, Chrome)

​
Troubleshooting

If you encounter issues after migration:
  1. Clear cache: Clear your browser cache and Shopify’s theme cache
  2. Check Theme Check: Run shopify theme check to identify problems
  3. Review console: Check browser DevTools for JavaScript errors
  4. Compare files: Use a diff tool to compare your customized files with the upstream version
  5. Rollback if needed: Restore your backup theme if critical issues arise
For more help, see the Troubleshooting guide.

​
Rolling Back

If you need to revert to your previous theme version:
1

From Shopify Admin

  1. Go to Online Store > Themes
  2. In the Theme library, find your backup theme
  3. Click Actions > Publish
2

From Git

Force pushing can overwrite history. Make sure you have backups before using git push --force.

​
Best Practices

  • Never modify core theme files directly - Use custom sections and snippets instead
  • Document your changes - Keep notes on customizations you’ve made
  • Update regularly - Don’t fall too far behind on updates
  • Test on development stores - Always test updates before going live
  • Use version control - Git makes migrations much easier

​
Next Steps