About the Domain DNS API

With the Domain DNS API you can manage DNS zones in Google's Cloud DNS. This allows you to connect domains that you've registered through Wix to non-Wix websites. You can also use the Domain DNS API to manage DNS records for external domains that are connected by nameservers to Wix sites.

Using the Domain DNS API you can:

• Preview DNS zones
• Manage DNS zones in Google's Cloud DNS

Learn more about:

• Registering domains through Wix with the Registered Domains API
• Connecting external domains to Wix sites with the Connected Domains API
• Managing Wix Premium subscriptions with the Resellers API

Before you begin

It’s important to note the following points before starting to code:

• The Domain DNS API is accessible via API keys. You can't access this API with a standard Auth header. We recommend authenticating calls with an API key for your main account instead of using a key for the relevant sub-account. But the responses to calls remain consistent across API keys, provided you have the necessary permissions.
• Wix limits DNS records to 50 values per type. External providers may support a different maximum number of DNS records for a specific type, Wix doesn't validate that you don't exceed these external limits.
• You can only update DNS zones for external domains that are connected by nameservers to a Wix site. You can't use the Domain DNS API for external domains that are connected by pointing to a Wix site because the DNS isn't saved in Wix for this connection type.

Use cases

• Update DNS records for a registered domain
• Connect an external domain by nameservers to a Wix site

Terminology

• Registered domain: Domain that's purchased, registered, and billed through Wix.
• External domain: Domain that has been purchased through an external provider, not Wix.
• Domain name: The domain name includes the top-level domain (TLD). Examples for TLDs are com, net, or org.
• DNS record: Database record in the Domain Name System that's used to map a human-readable URL to an IP address.
• DNS zone: A DNS zone is an administrative subdivision of the DNS namespace. When you Create a DNS zone the values are uploaded to Google's Cloud DNS.
• Account: Wix account that includes access to associated sites.
  • Team account: Account type that supports collaborative work by having multiple sets of login credentials. This is especially helpful for agencies and resellers when managing a large number of customer sites. In Wix Studio team accounts are called workspaces. An agency may have multiple workspaces in Wix Studio, while in Wix Editor they're limited to a single team account.
  • Sub-account: Account that's contained within another account, forming a hierarchical structure. The owners of the sub-account are only able to interact with sites that belong to the sub-account. This setup is particularly useful for agencies and resellers since it limits client access to relevant sites only.

Sample Use Cases & Flows: Domain DNS

This article shares a possible use case your implementation could support, as well as a sample flow. You're not limited to this use case, but it can be a helpful jumping off point for your planning.

Update DNS records for a registered domain

You could purchase a domain through Wix and then update the MX and TXT records. This allows you to connect the domain to a website that isn't build on Wix.

To update the DNS records for a registered domain:

1. Optional: In case the relevant site is a free Wix site, use the Resellers API to assign a Premium plan to it. Make sure to save the productInstanceId.
2. Use the Resellers API to create a product instance for the relevant domain TLD and privacy. Don't assign the product instance to a site, but keep it floating in the relevant account.
3. Call Create Registered Domain to start the domain registration process through Wix.
4. Use Get Registered Domain to confirm that the status has changed to "PENDING_REGISTRATION".
5. Call Update Dns Zone to change the MX and TXT records in Google's Cloud DNS.
6. Connect the domain to the external site.

Connect an external domain by nameservers to a Wix site

You could help Wix site owners connect an external domain by nameservers to their site. Note that you can't use Update DNS Zone for external domains that are connected by pointing.

To connect an external domain by nameservers to a Wix site:

1. Optional: In case the relevant site is a free Wix site, use the Resellers API to assign a Premium plan to it.
2. Register the domain through an external provider.
3. Call Create Connected Domain to start the connection process. Make sure to use {"connectionType": "NAMESERVERS"}.
4. Use Get Connected Domain Setup Info to retrieve the new DNS record values. You find them in connectedDomainSetupInfo.pointingRecords.aRecord.values and connectedDomainSetupInfo.pointingRecords.cnameRecord.value.
5. Use Update Dns Zone to change the A and CNAME records in Google's Cloud DNS.
6. Call Get Connected Domain to monitor the connected domain's dnsPropagationStatus and confirm that it changes to "COMPLETED".

Domain DNS Errors

This articles outlines error messages that might be issued when calling endpoints of the Domain DNS API.

Create DNS Zone Errors

Create DNS Zone might issue the following error messages:

HTTP status	Error code	Error message	Troubleshooting
NOT_FOUND (404)	USER_ID_NOT_FOUND	User id not found in request context.	Make sure to pass the correct authorization header.
NOT_FOUND (404)	TARGET_ACCOUNT_NOT_FOUND	Target account id not found in request context.	Make sure to pass the correct account ID in the header of the call.
NOT_FOUND (404)	DNS_ZONE_NOT_FOUND	No dns zone found for domain name <domainName>.	You must pass a dnsZone object when setting up a DNS zone in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_NOT_PERMITTED	Domain <domain> is not permitted to target account.	Make sure to pass the correct account ID in the header of the call. The target account must also have a Premium subscription that allows connecting a domain with the chosen TLD. See the Resellers API for more information.
FAILED_PRECONDITION (428)	DOMAIN_ALREADY_EXISTS	Domain <domain> already exists.	You can create a DNS zone in Google's Cloud DNS that already exists.
FAILED_PRECONDITION (428)	DOMAIN_DNS_EMPTY_RECORD_VALUE	Value of record <recordType> is empty.	You must pass values for each DNS record that you want to specify in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_MX_RECORD_VALUE_INVALID	Value of MX record <value> is invalid, it should start with a priority and then the mail server, for example "5 aspmx.l.google.com".	Make sure to use this format "5 aspmx.l.google.com" when specifying the value of an MX record in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_CNAME_RECORD_HOSTNAME_INVALID	Host name of the CNAME record $value is invalid, it should end with the domain name but not equal to it, for example "en.domain.com".	Make sure to use this format "en.domain.com" when specifying the value of a CNAME record in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_MX_RECORD_VALUE_INVALID	Multiple <recordType> records with the same hostName <hostName> not supported, the multiple values belong to the same hostName should be combined under one <recordType>.	Make sure that you pass all DNS record values that belong to the same type in a single values array of the relevant records.type object. You can't pass multiple record objects with the same record type.

Update DNS Zone Errors

Update DNS Zone might issue the following error messages:

HTTP status	Error code	Error message	Troubleshooting
NOT_FOUND (404)	USER_ID_NOT_FOUND	User id not found in request context.	Make sure to pass the correct authorization header.
NOT_FOUND (404)	TARGET_ACCOUNT_NOT_FOUND	Target account id not found in request context.	Make sure to pass the correct account ID in the header of the call.
FAILED_PRECONDITION (428)	DOMAIN_NOT_PERMITTED	Domain <domain> is not permitted to target account.	Make sure to pass the correct account ID in the header of the call. The target account must also have a Premium subscription that allows connecting a domain with the chosen TLD. See the Resellers API for more information.
FAILED_PRECONDITION (428)	DOMAIN_DNS_EMPTY_RECORD_VALUE	Value of record <recordType> is empty.	You must pass at least one value for each DNS record type that you want to specify in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_MX_RECORD_VALUE_INVALID	Value of MX record <value> is invalid, it should start with a priority and then the mail server, for example "5 aspmx.l.google.com".	Make sure to use this format: "5 aspmx.l.google.com", when specifying the value of an MX record in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_CNAME_RECORD_HOSTNAME_INVALID	Host name of the CNAME record $value is invalid, it should end with the domain name but not equal to it, for example "en.domain.com".	Make sure to use this format: "en.domain.com", when specifying the value of a CNAME record in Google's Cloud DNS.
FAILED_PRECONDITION (428)	DOMAIN_MX_RECORD_VALUE_INVALID	Multiple <recordType> records with the same hostName <hostName> not supported, the multiple values belong to the same hostName should be combined under one <recordType>.	Make sure that you pass all DNS record values that belong to the same DNS record type in the values array of the relevant record object. You can't pass multiple record objects that have the same record type.