In This Article

Migrate a Wix Site to a Self-Managed Headless Project

This guide shows you how to replace your Wix site's editor-built frontend with a self-managed, externally hosted one, so that your frontend serves your public website while your Wix site's data and business logic keep running your business, and Wix-hosted pages keep handling checkout, login, and account processes. The result is a self-managed headless project made up of your own frontend, backed by that Wix site's business logic and data.

Because you're moving a public web address between 2 hosts, most of the work happens safely in advance, and a small set of changes happen together at launch. For the architecture behind these steps, including how the domains and redirects fit together, see About Wix Site Migration to a Self-Managed Headless Project.

When you're done:

Your public website is served by your externally hosted frontend.
Your Wix-hosted-pages subdomain is your Wix site's primary domain and serves Wix-hosted checkout, login, and account pages.
All of your business data stays on the same Wix site.

This guide uses www.example.com for your public website and checkout.example.com for your Wix-hosted-pages subdomain.

Before you begin

Make sure you have:

A Wix site built with one of the Wix editors.
A self-managed frontend that already calls your Wix site's APIs through a headless client. See Add a Frontend to an Existing Wix Site.
A subdomain planned for your Wix-hosted pages. For example, checkout.example.com.
Access to your domain's DNS settings.

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

Step 1 | Prepare and test against a preview URL

Do everything in this step while your Wix site keeps serving your public domain. For example, www.example.com. Nothing in this step affects your published website.

Finish and test your frontend on a preview or staging URL.
In your site's Headless Settings, on your OAuth client, add your preview addresses:
- Add your preview URL to your allowed redirect domains.
- Add your preview login callback to your authorization redirect URIs. For example, https://preview.example.com/login/callback.
Set your Frontend link to your preview URL.
Test your API integration against your Wix site.
Lower the DNS TTL on your public-website and Wix-hosted-pages records to 300 seconds, 24 to 48 hours before you launch, so the switch propagates quickly. For example, lower the TTL for www.example.com and checkout.example.com.

At the end of this step, your published website is unchanged and your frontend works against preview addresses.

Note: You can test checkout and login end to end before launch, but not in full isolation. Wix-hosted pages still run on your site's current primary domain, for example, www.example.com, until you migrate, so a hybrid test runs checkout on your current domain and returns visitors to your preview URL.

Step 2 | Deploy your production frontend

Deploy your production build to your external host, and confirm it loads correctly on the host's own URL. Don't change any DNS or domain settings until you've verified the production build.

Step 3 | Update your OAuth settings for production

In Headless Settings, on your OAuth client, 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.
Set your Frontend link to your production frontend URL. For example, https://www.example.com.
Leave Login URL empty, unless you host a custom login page on your frontend. If you set it to a callback path, Wix can build invalid login URLs by appending paths to that value.
Click Save.

Step 4 | Point your public domain at your external host

Caution: The remaining steps change your site's domain. Don't start them until your production frontend is deployed and verified. Pointing your public domain at your external host, unassigning it from Wix, or reassigning your primary domain before the frontend is ready takes your public website offline.

At your domain registrar, update only the web DNS records for your public website:

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.

On your host, configure permanent (301) redirects for hostname canonicalization and for any old Wix page paths that changed in your frontend. For example, redirect http://www.example.com to https://www.example.com, and example.com to www.example.com. Then wait for DNS to propagate, which can take up to 48 hours.

Step 5 | Reassign the domains on your Wix site

In your site dashboard, go to Settings > Domains:

Unassign your public-website domain and its apex domain, if connected, from your Wix site. For example, www.example.com and example.com, respectively.
Connect your Wix-hosted-pages subdomain, for example, checkout.example.com, and set it as your site's primary domain. Complete any DNS steps Wix provides for the subdomain.

At the end of this step, your public domain serves your frontend, and your Wix-hosted-pages subdomain serves Wix-hosted pages on your Wix site. For example, www.example.com and checkout.example.com, respectively.

Step 6 | Set your Wix pages domain

In Headless Settings, scroll to the Manage URLs section.
In the Wix pages domain section, click Manage domain and set your Wix-hosted-pages subdomain. For example, checkout.example.com. For details, see Set a Domain for Wix-Hosted Pages.
Confirm your subdomain appears under Wix pages domain.

Step 7 | Verify your flows end to end

On your production frontend, test each flow:

Browse the public website: Loads your frontend. For example, www.example.com.
Request http, apex, or another hostname: Permanent (301) redirect to your canonical address. For example, https://www.example.com.
Request an old Wix page path: 301 to the matching frontend page, or an intentional 404.
Start and complete checkout: Redirect to your Wix-hosted-pages subdomain, for example, checkout.example.com, then back to your frontend.
Log in as a member: Login on your Wix-hosted-pages subdomain, for example, checkout.example.com, then a callback to your frontend.
Open a member account page: Account pages on your Wix-hosted-pages subdomain, for example, checkout.example.com, then a return to your frontend.
Send and receive email: Still works, because your email DNS records are unchanged.

Step 8 | Clean up after launch

Monitor your checkout and login flows for 24 to 48 hours.
Confirm your 301 redirects for canonical hostnames and old page paths, using your search console and a few old bookmarks.
Restore your DNS TTL values to normal.
Remove any preview addresses you no longer need from your OAuth redirect settings.

Step 9 | (Optional) Support multiple regional frontend domains

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

Point each regional web DNS 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-hosted-pages subdomain for all regions.
In your code, set your redirect-session return URL and your login redirect URI from window.location.origin on each redirect, so visitors return to the region they came from.