Migrate a Wix Site to a Self-Managed Headless Project

Replace your editor-built pages with your own externally hosted frontend, and keep managing your business from the same dashboard. Your data and business logic stay exactly the same, now running as your project's backend.

Most of the work happens safely before launch. Only the domain switch changes your live site, and it happens in a single coordinated step. To learn more, see About Wix Site Migration to a Self-Managed Headless Project.

When you're done:

• Your externally hosted frontend serves your public website on your main domain, such as www.example.com.
• Your project serves its Wix-hosted pages and backend on a subdomain, such as checkout.example.com.
• All of your business data stays in the same project.

Before you begin

Make sure you have:

• A frontend built to replace your editor-built pages as your public website, that already calls your project's APIs through a headless client. If you haven't built one yet, see Add a Frontend to an Existing Wix Site.
• An external host, a hosting provider outside of Wix, such as Vercel, Netlify, or AWS, to deploy your frontend to.
• A subdomain planned for your project, such as checkout.example.com.
• Access to your domain's DNS settings, usually available through your domain registrar or DNS provider, such as GoDaddy, Namecheap, or Cloudflare. If someone else manages your domain, such as an IT team or agency, arrange access with them.

Confirm that you're working with your production site, not a proof-of-concept or test site in the same account.

Step 1 | Build and test your frontend on a preview address

Do everything in this step while your editor-built site keeps serving your main domain. Nothing here affects your live website.

1. Finish and test your frontend on a preview or staging address from your external host.
2. In your project's Headless Settings, select your headless client's settings, then:
   1. Add your preview address to your Allowed redirect domains.
   2. Add your preview login callback to your Authorization redirect URIs. For example, https://preview.example.com/login/callback.
3. Set your Frontend link to your preview address.
4. Confirm that your frontend's API calls correctly read and write your project's data.
5. 24 to 48 hours before launch, note the current DNS TTL value on your main domain's record, such as www.example.com, then lower it to 300 seconds. TTL controls how long other computers on the internet cache your record before rechecking it, so a lower value means the switch in Step 4 reaches visitors in minutes instead of gradually over a day.

At the end of this step, your live website stays unchanged, and your frontend works correctly using your preview address.

Step 2 | Deploy your frontend to your external host

Deploy your frontend to your external host, and confirm it loads correctly at the temporary address your host assigns, before you connect your own domain. Don't change any DNS or domain settings until you've verified the deployment.

Step 3 | Add your production addresses to your headless client

1. In your project's Headless Settings, select your headless client's settings, then add your production addresses:
   • Allowed redirect domains: Your production frontend hostnames. Include both www and the apex domain if you use both. For example, www.example.com and example.com.
   • Authorization redirect URIs: Your exact production login callback URLs. For example, https://www.example.com/login/callback.
2. Set your Frontend link to your production frontend URL. For example, https://www.example.com.
3. Leave Login URL empty, unless you host a custom login page on your frontend, in which case set it to that page's URL. If you set it to a callback path instead, Wix can build invalid login URLs by appending paths to that value.
4. Click Save.

Step 4 | Switch your domains

Your main domain moves to your external host, and your Wix subdomain becomes your project's new primary domain, the address your project actually serves pages from. Wix-hosted pages like checkout and login load there instead of your old domain.

Follow the steps in order. If you point your main domain at your external host before you change the primary domain on Wix, Wix won't redirect your main domain to your subdomain during the switch.

1. At your domain registrar, point your main domain's CNAME or A record at your external host:
   • Point your www CNAME record or your apex A record to your external host. For example, www.example.com or example.com, respectively.
   • Leave your MX, SPF, DKIM, and DMARC records unchanged, so your email keeps working.
2. In your project dashboard, go to Settings > Domains. Connect your Wix subdomain, for example checkout.example.com, and set it as the project's primary domain. Complete any DNS steps Wix provides for the subdomain.
3. Unassign your main domain, and its apex domain if connected, from your project. For example, www.example.com and example.com, respectively.
4. On your host, set up permanent (301) redirects for both of the following:
   • From variations of your address, such as with or without www, or http instead of https, to your single canonical address, the official version search engines should use. For example, redirect http://www.example.com to https://www.example.com, and example.com to www.example.com.
   • If a page's path is different in your new frontend than it was on your editor-built pages, redirect from the old path to the new path.

DNS can take up to 48 hours to propagate, though the lowered TTL from Step 1 speeds this up. Until it does, different visitors can briefly see different things at www.example.com, depending on how quickly their own DNS cache picks up the change, so don't be alarmed if some visitors still reach your old setup for a while.

At the end of this step, your main domain, such as www.example.com, serves your frontend, and your Wix subdomain, such as checkout.example.com, is your project's primary domain and serves your project.

Step 5 | Set your Wix pages domain

Point the Wix pages domain setting at your subdomain, so that visitors stay on your subdomain, rather than a default Wix address, during Wix-hosted flows, such as checkout and login.

1. In your project's Headless Settings, go to the Manage URLs section.
2. In the Wix pages domain section, click Manage domain and set your subdomain. For example, checkout.example.com. For details, see Set a Domain for Wix-Hosted Pages.
3. Confirm your subdomain appears under Wix pages domain.

Step 6 | Verify your flows end to end

On your production frontend, test each flow:

• Browse the public website: Loads your frontend.
• Request http or another variation of your domain, such as the apex instead of www: Redirects to your canonical address. For example, from http://www.example.com to https://www.example.com.
• Request an old Wix page path: Redirects to the matching frontend page, or an intentional 404.
• Start and complete checkout: Redirects to your subdomain then back to your frontend.
• Log in as a member: Redirects to your subdomain to log in, then a callback to your frontend.
• Open a member account page: Redirects to your subdomain, then back to your frontend.
• Call your project's backend: Confirm any HTTP functions or other backend URLs still respond correctly, and update them if their domain changed.
• Send and receive email: Still works, because you left your email DNS records unchanged.

Step 7 | Clean up after launch

Now that you've launched, confirm everything is working correctly and remove any settings you no longer need.

• Monitor your Wix-hosted flows, such as checkout and login, for 24 to 48 hours.
• Confirm the redirects to your canonical address and from old page paths, using Google Search Console and old bookmarks.
• Restore your DNS TTL value to what you noted in Step 1, before you lowered it.
• Remove any preview addresses you no longer need from your headless client's redirect settings.

Step 8 | (Optional) Support multiple regional frontend domains

If your frontend uses several regional domains, such as .com, .eu, and .cz, a single headless client and Wix subdomain can serve all of them:

• Point each region's CNAME or A record at your external host.
• Add every frontend hostname to your Allowed redirect domains.
• Add every regional login callback to your Authorization redirect URIs.
• Keep a single Wix subdomain for all regions.
• In your code, set your redirect session's return URL and your login callback URL from window.location.origin on each redirect, so visitors return to the region they came from.

See also

• About Wix Site Migration to a Self-Managed Headless Project
• Add a Frontend to an Existing Wix Site
• Set a Domain for Wix-Hosted Pages
• Allow Redirect URIs and Domains
• Add a Frontend Link