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 dnsRecords array doesn't include the default nameserver record. Instead, the default nameserver is stored in a separate read-only nsRecord object.
  • 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, or org.
  • 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.
Was this helpful?
Yes
No

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 domainUnable 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 domainDomain <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 typeInvalid 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 recordAdditional 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_VALIDWix 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_ASMissing siteId for assignAs <assignAs>.Make sure to pass a site ID when setting up a primary domain or redirect.
PERMISSION_DENIED (403)DOMAINS_PERMISSION_DENIEDPermission 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_PERMITTEDDomain <domain> is not permitted to target account.Make sure that you have permissions to access the account.
PERMISSION_DENIED (403)DOMAINS_NO_THROTTLER_KEYCannot consume this service.Make sure that your app has the Manage Domains permission scope.
PERMISSION_DENIED (403)DOMAINS_SITE_NOT_PERMITTEDSiteId: <siteId> is not permitted to target account.Check that site belongs to the account.
PERMISSION_DENIED (403)INVALID_DOMAINS_PREVIEW_RECORDSPreview 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.
Was this helpful?
Yes
No

Domain Connection Object

Attributes
domainstringformat HOSTNAME
Domain name. Both root domains and subdomains are supported.

connectionTypestring
4 supported values:
UNKNOWNPOINTINGNAMESERVERSINTERNAL
How the domain is connected to the Wix site. Note: When you connect a domain, you can only pass POINTING or NAMESERVERS in the request. For subdomains, you aren't allowed to pass any connection type.

assignAsstring
3 supported values:
UNKNOWNPRIMARYREDIRECT
Whether the domain is assigned as primary domain or redirect. Read more about primary and redirected domains. Note: When you connect a domain or subdomain, you can't pass UNKNOWN in the request.

suppressNotificationsboolean
Whether the site owner receives standard email notifications from Wix about the domain connection. Returned only when set to true. Default: false

ONE OF:


nameserverInfoobject
Information about domains connected using nameservers. Available only for {"connectionType": "NAMESERVERS"}.

pointingInfoobject
Information about domains connected by pointing. Available only for {"connectionType": "POINTING"}.

subdomainInfoobject
Information about subdomains. Available only for subdomains.
Was this helpful?
Yes
No

PostConnect Domain

Deprecated

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Domains
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/domain-connect/v1/connect-domain

Was this helpful?
Yes
No