Migrate from the online store to Hydrogen
This guide outlines considerations when migrating from the online store to Hydrogen.
Incremental adoption / proxy routesAnchor link to section titled "Incremental adoption / proxy routes"
Some merchants might want to adopt a Hydrogen storefront incrementally. For example, by first launching a Hydrogen storefront with just a product page and temporarily using the online store for everything else. You can do this by proxying specific routes. Learn more.
Shared cartsAnchor link to section titled "Shared carts"
To share a cart between a Hydrogen storefront and the online store, such as when you're incrementally adopting Hydrogen, you’ll need to update your online store to use the Storefront API for carts instead of using Liquid carts. Learn more.
Subdomain for checkoutAnchor link to section titled "Subdomain for checkout"
Regardless of whether you're using the online store or Hydrogen, customers are always directed back to a Shopify-hosted checkout. Traditionally, a checkout URL might look something like
It’s common to set up a subdomain for the purpose of checkout, for example
checkout.example.com. To do this:
Set the Target to Online Store.
Set the Domain type to Primary.
Configure routingAnchor link to section titled "Configure routing"
When you're migrating from an online store to a custom storefront, you can define your own routes. For example, product routes don't need to conform to a
/products/[handle] URL path.
If you change routes, for example to
/p/[handle], then set up redirects to help customers and search engines find your resources. This is especially important if you change the
/cart route, which is linked to from the breadcrumbs at checkout.
The following is an example of setting up a redirect from
Shareable discount code linksAnchor link to section titled "Shareable discount code links"
The online store has built-in support for shareable discount code links, with the URL structure
/discount/[discount_code]. These links attach the discount code in the URL to a customer's cart, which is then applied automatically at checkout.
If you use these shareable discount code links with your customers in the online store channel, then you might want to have the same functionality in your custom storefront channel, on a
We recommend that the logic you set in this route does the following:
- Check if a cart exists
- If a cart exists, then update the cart with the discount code
- If a cart doesn't exist, then create a cart and include the discount code
- Redirect to another page. For example, the home page
Cart PermalinksAnchor link to section titled "Cart Permalinks"
The online store has built-in support for cart permalinks, which link customers to Shopify checkouts or the online store cart, with pre-loaded items to complete a purchase.
Cart permalinks have the following URL structure:
You can also append query parameters to a cart permalink URL to include additional information. Learn more.
If you use cart permalinks with your customers in the online store channel, including the reordering feature available to new customer accounts, then you will want to include the same or similar functionality on the
/cart route of your custom storefront channel.
Online store redirectsAnchor link to section titled "Online store redirects"
If you decide to keep the online store channel accessible, be sure to set up redirects to take customers to your Hydrogen storefront. Assuming your Hydrogen storefront maintains the online store URL structure, you could do something like the following example:
Product feedsAnchor link to section titled "Product feeds"
Canonical links to legacy domainsAnchor link to section titled "Canonical links to legacy domains"
When migrating to a custom storefront, if you decide to keep the online store channel accessible, add canonical links to all of the online store's page templates. The following is an example:
Make sure that the canonical URL reflects any structural changes that you've made to the URL. The following is an example:
Password protectionAnchor link to section titled "Password protection"
Online store password protection also affects Hydrogen checkouts. To remove password protection:
From the Shopify admin, under Sales channels, click Online Store > Preferences.
In the Restrict store access section, deselect Restrict access to visitors with the password.
NotificationsAnchor link to section titled "Notifications"
You can update notifications to use the same domain as your Hydrogen storefront.
From the Shopify admin, click Settings > Notifications.
Update the Notification URLs setting.
- Go live with Hydrogen go live on Hydrogen for merchants ready to publish their new Hydrogen storefront.