About the Domain Connections API
Deprecation Notice:
Domain Connections has been replaced with Connected Domains and will be removed on December 31, 2023.
With the Domain Connections API you can connect a root domain or subdomain to a Wix site. You can only connect external domains.
The domain can be assigned as a primary domain or a redirect. You can read more about primary and redirected domains.
Before you begin
- You can only connect domains to a Wix site with an active Premium plan that supports domains with the relevant TLD.
- The
dnsRecordsarray doesn't include the default nameserver record. Instead, the default nameserver is stored in a separate read-onlynsRecordobject. - Wix doesn't manage the DNS records for domains connected by pointing.
Terminology
- Wix Domain: A domain owned by Wix and billed through Wix.
- External Domain: A domain owned by an external provider, not Wix.
- DNS: The Domain Name System helps users identify computers connected to the internet.
- Nameserver: A server component of the DNS that stores human-readable domain names.
- Pointing: A connection type for cases where the DNS is hosted outside of Wix. Read more about connecting a domain to Wix by pointing.
- TLD: Top-level domain. For example,
com,net, ororg. - Root domain: Highest hierarchy level of the DNS.
Consists of the domain name and TLD. For example,
my-example-domain.com. - Subdomain: Lower hierarchy level of the DNS. For example,
support.my-example-domain.com.
Domains Errors
This articles outlines error messages that might be issued when calling endpoints of the Domain Search API.
Connect Domain Errors
The Connect Domain endpoint might issue the following error messages:
HTTP status | Error code | Error message | Troubleshooting |
|---|---|---|---|
INVALID_ARGUMENT (400) | Invalid domain | Unable to connect domain <domainName>, it is available for purchase. | You must purchase the domain before you can connect it to a Wix site. |
INVALID_ARGUMENT (400) | Invalid domain | Domain <domainName> is restricted. | Not all TLDs are supported for Wix sites. Contact the Wix B2B sales team for a list of supported TLDs and then try connecting a domain that's supported. |
INVALID_ARGUMENT (400) | Invalid connection type | Invalid connection type: <connectionType>. | Choose a connection type that's supported for the domain. To connect a root domain, you can only connect via POINTING or NAMESERVERS. For subdomains, you aren't allowed to pass any connection type. |
INVALID_ARGUMENT (400) | Invalid type of record | Additional DNS records can not be provided for <connectionType>. | It isn't supported to pass additional DNS record information in the request. Omit the additional DNS records and try again. |
INVALID_ARGUMENT (400) | DOMAINS_GUID_NOT_VALID | Wix site id / Wix account ID is invalid. | Check that the site and account ID are correct. |
INVALID_ARGUMENT (400) | DOMAINS_MISSING_SITE_ID_FOR_ASSIGN_AS | Missing siteId for assignAs <assignAs>. | Make sure to pass a site ID when setting up a primary domain or redirect. |
PERMISSION_DENIED (403) | DOMAINS_PERMISSION_DENIED | Permission denied for target accountId: <targetAccountId>. | Check that the account ID is correct and that you have permissions to access it. |
PERMISSION_DENIED (403) | DOMAINS_DOMAIN_NOT_PERMITTED | Domain <domain> is not permitted to target account. | Make sure that you have permissions to access the account. |
PERMISSION_DENIED (403) | DOMAINS_NO_THROTTLER_KEY | Cannot consume this service. | Make sure that your app has the Manage Domains permission scope. |
PERMISSION_DENIED (403) | DOMAINS_SITE_NOT_PERMITTED | SiteId: <siteId> is not permitted to target account. | Check that site belongs to the account. |
PERMISSION_DENIED (403) | INVALID_DOMAINS_PREVIEW_RECORDS | Preview records are missing A and/or CName and/or NS for domain: <domainName>. | Make sure to pass the releavant DNS records. |
PERMISSION_DENIED (403) | DOMAINS_GUID_NOT_FOUND | - | Make sure to pass a valid account ID. |
ONE OF:
This method has been replaced with CreateConnectedDomain, and will be removed on December 31, 2023.
Connects a root domain or subdomain to a Wix site.
You must pass the relevant Wix account ID in the header of the call. You may also pass a Wix site ID in the header. If you omit the site ID, you have to call Connect Domain again before the site owners can use the domain.
You can't pass the default nameserver record in the dnsRecords array of
the call's body. This results in an error.
You can only connect external domains using this endpoint. Domains purchased and billed through Wix can't be connected in this way to a Wix site.
The domain can be assigned as a primary domain or a redirect. You can read more about primary and redirected domains.
Important: This call requires an account level API key and cannot be authenticated with the standard authorization header.