1. Configuring external DNS

In this guide, you will learn how to configure external domains for your FastStore and VTEX website. The process involves the following steps:

Setting up your external DNS provider to point your custom domain to your VTEX website. Custom domains can be purchased from any domain registration platform.
Configuring your custom domains in VTEX Account Settings.
Associating your custom domains with your FastStore project.

Besides making your FastStore website accessible via a custom domain, VTEX Checkout will also be operational as soon as you complete this guide. You'll then be ready to continue configuring other VTEX solutions, such as Order Placed, Login, and My Account.

Before you begin

Develop your FastStore project by following the Getting Started track.
Deploy your FastStore project.
Buy the desired domain.
Redirect the root domain to the www subdomain.

Instructions

If you still need to configure other VTEX solutions, please use a fictitious domain name while taking the following steps. Once you have set up all the desired integrations, repeat this guide using your final domain to make your website publicly available to end-users.

Step 1 - Creating DNS records

Access your domain provider's website.
Create a CNAME DNS record for your www domain (e.g., www.mystore.com) that points to www.{rootDomain}.cdn.vtex.com (e.g., www.mystore.com.cdn.vtex.com). Check your domain provider's documentation for more information.
Now, create a CNAME record for the secure subdomain (e.g., secure.mystore.com) that points to secure.{rootDomain}.cdn.vtex.com (e.g., secure.mystore.com.cdn.vtex.com). This subdomain will be used by the Checkout, Order Placed, Login, and My Account pages.

Please note that the configured addresses may not be immediately available to everyone due to DNS propagation, which can take 24-48 hours to complete.

Step 2 - Putting your account into production

To proceed, make sure your store is active and in production, to do this, follow the steps in the article Putting your account into production.

Step 3 - Configuring domains in VTEX Account Settings

Now, you must set up your VTEX account to use the DNS records created in the previous step.

For more information about store domain configuration, see the Configuring the store domain guide.

On VTEX Admin, click your profile avatar, which can be identified by the first letter of your email address.
Access Account Settings > Account.
Go to the Stores tab and in the Hosts table, click the menu (⋮) and choose Edit.
In the Hosts field, enter your main domain (e.g., www.mystore.com) to the list.
Click Add.
Add the secure subdomain (e.g., secure.mystore.com) to the list.
${"base64":" ","img":{"width":1210,"height":372,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":17404,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/account-settings-new___2e13bee3041e8505922a737b94652ca6.png"}}$
Add the root domain as well; e.g., if your domain is www.mystore.com, add mystore.com. For a complete setup, you must add three hosts for each domain:
- www.mystore.com (store domain)
- mystore.com (root domain)
- secure.mystore.com (checkout/myaccount subdomain)

To ensure a seamless checkout experience, all subdomains used by your store must be added to the host list. For more information, see the Adding subdomains to the host list section.

Click the Save button.

Step 4 - Associating your custom domain with your FastStore project

Back to your FastStore project, you must also configure your project to point to the right addresses and domains.

Open your FastStore project in any code editor of your preference.
Open the discovery.config.js file.
Update the storeUrl, secureSubdomain, checkoutUrl, loginUrl, and accountUrl properties as in the following:
- storeUrl: https://{subdomain}.{rootDomain}
- secureSubdomain: https://{subdomain}.{rootDomain}
- checkoutUrl: https://{subdomain}.{rootDomain}/checkout
- loginUrl: https://{subdomain}.{rootDomain}/api/io/login
- accountUrl: https://{subdomain}.{rootDomain}/api/io/account

Take the following example of how this code block would look after configuring a store with the www.mystore.com domain and secure subdomain:

/discovery.config.js


_15...
_15
_15// Default channel
_15channel: '1',
_15
_15+  // Production URLs
_15+  storeUrl: 'https://www.mystore.com',
_15+  secureSubdomain: 'https://secure.mystore.com',
_15+  checkoutUrl: 'https://secure.mystore.com/checkout',
_15+  loginUrl: 'https://secure.mystore.com/api/io/login',
_15+  accountUrl: 'https://secure.mystore.com/api/io/account',
_15
_15// Lighthouse CI
_15lighthouse: {
_15...

Save your changes.
Open the vtex.env file.
Add the SITE_HOST key with the main domain specified in Configuring domains in VTEX Account Settings as the value.

/vtex.env
_10+ SITE_HOST=www.mystore.com
Save your changes.
Open a Pull Request, commit your changes, and deploy them to main.

For stores with prefixed domains, add the subDomainPrefix property to discovery.config.js to ensure product visibility in the secured environment. For more information, see the Adding subDomainPrefix for prefixed domains section.

Step 5 - Configuring the CDN workflow (Only for new go-lives)

If your FastStore website is going live for the first time, open a ticket with VTEX Support and specify that you need to configure the CDN workflow for the secure and main domains of your store.

Remember to include the following information in your ticket:

Your VTEX account name.
The secure and main domains of your store.

The VTEX team will evaluate your request and take the necessary actions to configure your account's CDN workflow.

Configuring custom domain prefixes

To ensure your store operates efficiently, it's important to configure custom domain prefixes correctly for both checkout and secure product viewing. There are some scenarios where you need to configure custom domains prefixes:

Stores with multiple subdomains: Add all the subdomains to the host list.
Stores with prefixed domains: Add subDomainPrefix for prefixed domains.

Adding subdomains to the host list

To ensure a seamless checkout experience, all subdomains used by your store must be added to the host list. If the store operates without the www. domain, you must include both the www. and non-www. domains in the hosts' list.

Stores with custom prefixes, like shop.mystore.com, need both the prefix and main domain (shop.mystore.com and mystore.com) added. This guarantees that the checkout process works seamlessly when customers access the store with or without www. or any other custom prefix.

Adding `subDomainPrefix` for prefixed domains

To ensure customers can view products in the secured environment on your store final domain, add the subDomainPrefix property to the dicovery.config.js file. The subDomainPrefix property maintains compatibility between cookies set in the storefront and the secure environment.

To add the subDomainPrefix property, follow these steps:

Open your FastStore project in a code editor of your preference.
Open the discovery.config.js file.
Navigate to the api object and add the following:

_10// Platform specific configs for API _10api: { _10 ... _10 subDomainPrefix: ['xxx'] _10},

Replace 'xxx' from subDomainPrefix property with the actual subdomain prefix (e.g., ['b2b']). If you have multiple prefixes, add them as an array of strings (e.g., ['b2b', 'dev']).
Save your changes.
Open a Pull Request, commit your changes, and deploy them to main.