Site transfer

In this guide, you will learn how to transfer a Headless Platform site from one WP Engine account to another.

Overview

Transferring a Headless Platform site involves coordinating between the source and destination accounts to ensure a smooth migration. This process is useful when:

• Moving a site to a different organization or billing account
• Consolidating sites under a single account
• Transferring ownership of a project
• Transferring environments from sandbox accounts

The transfer process consists of three main steps:

1. Contact WP Engine support to re-parent the WordPress installs to the destination account
2. Document Headless environments by documenting environment variables and domain configurations
3. Recreate the Headless app in the destination account and reconnect domains

Prerequisites

Before beginning the transfer process, ensure you have:

• Access to both the source and destination WP Engine accounts
• Access to the Git repository (GitHub, Bitbucket, etc.) with permissions to connect it to the WP Engine app
• A clear understanding of which app and environments need to be transferred
• Documented all custom domain mappings and environment variables

Transfer process

1: Re-parent relevant WordPress installs

WordPress site transfers between accounts must be initiated through WP Engine support. You cannot transfer sites directly through the User Portal.

1. Log in to the WP Engine User Portal from the destination account
2. Start a chat with our Technical Support team by clicking on the chat bubble in the bottom right corner of the User Portal
3. Provide the following information:
   • Source account name
   • Source account Support Pin
   • Destination account name
   • Destination account Support Pin

You will need to have Owner or Full with billing access to both accounts.

2. Document Headless environments

While waiting for support to process your request:

1. Document environment variables: Export all environment variables for each environment that will be transferred. See Environment Variables
2. Record custom domain mappings: Record all custom domains and their configurations. See Domain mapping for details.

3. Re-create Headless environments

Once the WordPress installs have been re-parented, you'll need to create new Headless apps in the destination account, configure environment variables, and move your domains over.

WP Engine support will coordinate the re-parent process and notify you when it's complete. After the WordPress installs are re-parented to the destination account:

1. Create app: Log in to the destination account and click "+ Create app" at the top. See Creating an App
2. Configure your app: Chose the Git provider, repository, app name, region, and hit "Next".
3. Link re-parented WordPress install: On this page, select "I already have my WordPress instance" and chose the relevant install.
4. Reconfigure environment variables: On the bottom of this page, add any relevant environment variables. If you exported your environment variables, you can import them.
5. Test deployment: Create the app and review the deployed site to ensure everything looks correct.
6. Repeat for any other apps: If more than 1 app needs to be transferred, follow the above steps again for each app.
7. Update domain mappings: Lastly, move the domains over! This process requires manually removing the
   domain from the old app and connecting it to the new app. This does cause downtime, so if it is
   in production, choose a time with minimal traffic.

Verify the transfer

After completing the transfer, confirm everything is working correctly:

1. Check app deployment: Verify that the app in the destination account has deployed successfully
2. Test the site: Visit your deployed site and test key functionality to ensure everything works as expected
3. Verify domains: Confirm custom domains are resolving correctly and serving the new app
4. Review environment variables: Double-check that all necessary environment variables are configured
5. Test builds: Trigger a new build to ensure the deployment pipeline is working properly
6. Clean up (optional): Once verified, you may delete the old app from the source account

If everything is working correctly, your Headless Platform site has been successfully transferred to the destination account.

Getting help

If you encounter issues during the transfer process, contact WP Engine support.