# About the DNS Propagation API

The DNS Propagation API allows you to monitor and validate the DNS record configuration. 

With the DNS Propagation API you can:

+ [Retrieve](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/get-dns-propagation) the DNS propagation status for domains.
+ Monitor DNS record configuration and propagation progress.
+ Get detailed information about DNS record misconfigurations.
+ Check whether required DNS records are properly set up.

Learn more [about domain propagation](fallback::https://support.wix.com/en/article/about-domain-propagation).

## Before you begin

It's important to note the following before starting to code:

+ We recommend authenticating calls with an API key for your main account instead of using a key for the relevant child account. This won't affect 
  the responses to calls, which remain consistent across API keys, provided you have the necessary permissions.
+ DNS propagation can take up to 48 hours to complete globally. The API accounts for this by automatically scheduling recurring checks over the propagation period.
+ The DNS propagation process starts every time a non-pointing domain's DNS records change, not only when the domain is newly set up. Note that for pointing domains, that manage their zone files outside of Wix, DNS propagation monitoring isn't automatically triggered when external changes are made.
+ For managed domains that use Wix nameservers, DNS records are automatically re-resolved every 4 days to ensure ongoing accuracy and detect any changes.

## Use cases

+ [Monitor DNS propagation after domain connection.](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/sample-flows#monitor-dns-propagation-after-domain-connection)
+ [Troubleshoot domain connectivity issues.](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/sample-flows#troubleshoot-domain-connectivity-issues)

## Terminology

+ **Domain:** Domain name including TLD (top-level domain).
+ **TLD:** [Top-level domain](fallback::https://en.wikipedia.org/wiki/Top-level_domain). For example, "com", "net", or "org".
+ **DNS:** [Domain Name System](fallback::https://en.wikipedia.org/wiki/Domain_Name_System) of the internet.
+ **DNS propagation:** The process of DNS record changes spreading across DNS servers globally. 
  It begins following any changes to a domain's DNS records and may take up to 48 hours to complete.
+ **Expected DNS records:** The DNS records that should be configured for the domain to work properly with Wix.
+ **Actual DNS records:** The DNS records currently configured for the domain.
+ **Wix nameservers:** DNS servers operated by Wix that can be detected in a domain's NS records.

@sdk_package_setup

# DNS Propagation API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Monitor DNS propagation after domain connection

When a Wix user connects a custom domain to their Wix site, you need to verify that the DNS records are properly configured and propagated. This flow helps you monitor the propagation status and provide feedback to Wix users about their domain setup.

To monitor DNS propagation after domain connection:

1. Call [Get DNS Propagation](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/get-dns-propagation) using the domain name as the `dnsPropagationId` parameter to retrieve the current propagation status.

2. Check the `status` field in the response:
   - If `IN_PROGRESS`: The DNS records are still being checked and propagated. Continue monitoring.
   - If `SUCCEEDED`: All DNS records are properly configured and propagated. The domain is ready to use.
   - If `FAILED`: 1 or more DNS records are misconfigured. Continue below for troubleshooting.

3. If the status is `FAILED`, examine the `failureInfo` object to identify which DNS record types failed:
   - Check `invalidRecords` array to see which record types need attention.
   - Review the corresponding `invalidARecordInfo`, `invalidNsRecordInfo`, or `invalidCnameRecordInfo` objects for detailed comparisons.

4. For each failed record type, compare the `expectedDnsRecords` and `actualDnsRecords` arrays to identify the specific DNS configuration changes needed.

5. Provide the Wix user with clear instructions on which DNS records to update at their domain registrar, using the expected values from the API response.

6. Continue calling [Get DNS Propagation](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/get-dns-propagation) periodically to monitor progress. Since DNS propagation can take up to 48 hours, check the status every few hours rather than continuously.

## Troubleshoot domain connectivity issues

When a domain isn't working properly with a Wix site, you can use the DNS Propagation API to diagnose DNS configuration problems and guide Wix users toward solutions.

To troubleshoot domain connectivity issues:

1. Call [Get DNS Propagation](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/get-dns-propagation) using the domain name as the `dnsPropagationId` to get the current DNS propagation status and configuration details.

2. Analyze the overall propagation status:
   - If `SUCCEEDED`: DNS records are properly configured. The connectivity issue may be elsewhere.
   - If `IN_PROGRESS`: DNS changes may still be propagating. Wait for propagation to complete.
   - If `FAILED`: DNS records are misconfigured. Continue with DNS troubleshooting.

3. Check the `dnsResolverIncludesWixNs` field to verify name server configuration:
   - If `true`: Wix name servers are detected, indicating proper NS record configuration.
   - If `false` or `null`: Name servers may not be properly configured for Wix.

4. Examine the `failureInfo.invalidRecords` array to identify which specific DNS record types are causing problems.

5. For each invalid record type, review the detailed information:
   - Compare `expectedDnsRecords` with `actualDnsRecords` to see exactly what's wrong.
   - Provide specific instructions for correcting each misconfigured record type.

6. Guide the Wix user to make the necessary DNS changes at their domain registrar using the expected DNS record values from the API response.

7. After the Wix user makes changes, call [Get DNS Propagation](fallback::https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/get-dns-propagation) again to verify the updates and monitor the new propagation status.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

ID of the Wix account associated with the event.

accountId

ID of the parent Wix account. Only included when accountId belongs to a child account.

parentAccountId

ID of the Wix site associated with the event. Only included when the event is tied to a specific site.

siteId

AccountInfo

identityType

IdentificationData

WebhookIdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

data

eventType

The identification type and identity data.

instanceId

MessageEnvelope

ID of the DNS propagation to check the propagation status for.
Identical to the domain name, including [TLD](https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/introduction#terminology).

dnsPropagationId

CheckDnsPropagationRequest

Retrieved DNS propagation with current status.

CheckDnsPropagationResponse

CreateDnsPropagationRequest

CreateDnsPropagationResponse

The DNS (Domain Name System) propagation object contains information for a domain.
Tracks whether the DNS records are correctly configured and propagated globally.
Learn more [about DNS propagation](https://support.wix.com/en/article/about-domain-propagation).

Date and time the DNS propagation was created.

createdDate

Whether Wix name servers were detected among the domain's name servers.
For subdomains, this value matches the root domain's setting.

dnsResolverIncludesWixNs

Domain name, including the [TLD](https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/introduction#terminology). Both root domains and subdomains are supported.

domain

ID of the DNS propagation. Identical to the domain name, including the [TLD](https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/introduction#terminology) (top-level domain).

Revision number, which increments by 1 each time the DNS propagation
is updated. Ignored when creating a DNS propagation.

revision

Current status of the DNS propagation. Can take up to 3 days to complete.

status

Date and time the DNS propagation was updated.

updatedDate

DnsPropagation

Details about DNS propagation failure, including which record types failed.
Only present when `status` is `FAILED`.

statusInfo

Hostname for the DNS record. For example, `domain.com` or `mail.domain.com`. Supports both root domains and subdomains.

hostName

Values associated with the DNS record. For example, IP addresses for A records or server names for NS records.

Min: 1 value
Max: 10 values

values

DnsRecord

Details about the A record for which the DNS propagation has failed.
Includes all expected and current values of the A record.

Details about the CNAME record for which the DNS propagation has failed.
Includes all expected and current values of the CNAME records.

Details about the NS (nameserver) record for which the DNS propagation has failed.
Includes all expected and current values of the NS record.

The DNS record types that failed propagation.

Max: 3 invalid records

invalidRecords

FailedStatusInfo

ID of the DNS propagation to retrieve. Identical to the domain name, including [TLD](https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/introduction#terminology).

GetDnsPropagationRequest

GetDnsPropagationResponse

The propagation of the A record has failed.

The propagation of the NS record has failed.

The propagation of at least one CNAME record has failed.

InvalidRecord

DNS records currently configured in the external database. Note that there can only be a single A and NS record.

actualDnsRecords

The DNS records that should be configured in the external database. Note that there can only be a single A and NS record.

Max: 10 DNS records

expectedDnsRecords

InvalidRecordInfo

ID of the DNS propagation to schedule a check for.
Identical to the domain name, including [TLD](https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/introduction#terminology).

ScheduleDnsPropagationChecksRequest

ScheduleDnsPropagationChecksResponse

DNS propagation completed successfully. All required DNS records are properly configured and propagated.

DNS propagation failed. One or more DNS records are incorrectly configured or haven't propagated.

DNS propagation is in progress. Check again later for updated status.

Status

ID of the DNS propagation to synchronize.
Identical to the domain name, including [TLD](https://dev.wix.com/docs/api-reference/account-level/domains/dns-propagation/introduction#terminology).

Whether to perform a dry run without making actual changes.

If true, reports sync issues without applying any fixes.
If false, attempts to resolve detected issues.

Default: `false`

dryRunEnabled

SyncDnsPropagationDomainRequest

SyncDnsPropagationDomainResponse

value

BoolValue

Int64Value

ListValue

NullValue

StringValue

fields

Struct

nanos

seconds

Timestamp

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

bodyAsJson

ActionEvent

A sequence number that indicates the order of updates to an entity. For example, if an entity was updated at `16:00` and then again at `16:01`, the second update will always have a higher sequence number.
You can use this number to make sure you're handling updates in the right order. Just save the latest sequence number on your end and compare it to the one in each new message. If the new message has an older (lower) number, you can safely ignore it.

entityEventSequence

Fully Qualified Domain Name of an entity. This is a unique identifier assigned to the API main business entities.
For example, `wix.stores.catalog.product`, `wix.bookings.session`, `wix.payments.transaction`.

entityFqdn

ID of the entity associated with the event.

entityId

Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example, `2020-04-26T13:57:50.699Z`.

eventTime

Event ID. With this ID you can easily spot duplicated events and ignore them.

If present, indicates the action that triggered the event.

originatedFrom

Event action name, placed at the top level to make it easier for users to dispatch messages.
For example: `created`/`updated`/`deleted`/`started`/`completed`/`email_opened`.

slug

Whether the event was triggered as a result of a privacy regulation application
(for example, GDPR).

triggeredByAnonymizeRequest

DomainEvent

body

entityAsJson

Indicates the event was triggered by a restore-from-trashbin operation for a previously deleted entity

EntityCreatedEvent

deletedEntityAsJson

EntityDeletedEvent

Since platformized APIs only expose PATCH and not PUT we can't assume that the fields sent from the client are the actual diff.
This means that to generate a list of changed fields (as opposed to sent fields) one needs to traverse both objects.
We don't want to impose this on all developers and so we leave this traversal to the notification recipients which need it.

currentEntityAsJson

EntityUpdatedEvent

deletedDate

RestoreInfo

Retrieves DNS propagation status for a domain.

Use this method to check if DNS records are properly configured and propagated after connecting a custom domain,
during domain setup to see required DNS records, or to monitor ongoing propagation status after making DNS changes.

Example of retrieving DNS propagation status when DNS records are still being checked and propagated.

Get DNS Propagation Status - In Progress

GetDnsPropagation

Example of retrieving DNS propagation status when all DNS records are properly configured and propagated.

Get DNS Propagation Status - Success Case

Retrieves the DNS propagation status for a domain to check if DNS records are properly configured and propagated.

Get DNS Propagation Status

Manage Domains

Dns Propagation

_createdDate

_updatedDate

GetDnsPropagationRequestSignature

addressLine1

addressLine2

city

country

formatted

postalCode

subdivision

Address

GoogleProtoDuration

latitude

longitude

Location

name

number

StreetAddress

import { dnsPropagation } from "@wix/dns-propagation";

async function getDnsPropagationInProgress() {
  const response = await dnsPropagation.getDnsPropagation("newdomain.com");
  
  return response;
}

/* Promise resolves to:
 * {
 *   "_id": "newdomain.com",
 *   "domain": "newdomain.com",
 *   "revision": "1",
 *   "_createdDate": "2024-01-15T16:00:00.000Z",
 *   "_updatedDate": "2024-01-15T16:00:00.000Z",
 *   "status": "IN_PROGRESS",
 *   "dnsResolverIncludesWixNs": false
 * }
 */


import { dnsPropagation } from "@wix/dns-propagation";

async function getDnsPropagationSuccess() {
  const response = await dnsPropagation.getDnsPropagation("mystore.com");
  
  return response;
}

/* Promise resolves to:
 * {
 *   "_id": "mystore.com",
 *   "domain": "mystore.com",
 *   "revision": "3",
 *   "_createdDate": "2024-01-10T08:00:00.000Z",
 *   "_updatedDate": "2024-01-12T14:30:00.000Z",
 *   "status": "SUCCEEDED",
 *   "dnsResolverIncludesWixNs": true
 * }
 */


import { dnsPropagation } from "@wix/dns-propagation";

async function getDnsPropagation() {
  const response = await dnsPropagation.getDnsPropagation("example.com");
  
  return response;
}

/* Promise resolves to:
 * {
 *   "_id": "example.com",
 *   "domain": "example.com",
 *   "revision": "1",
 *   "_createdDate": "2024-01-15T10:30:00.000Z",
 *   "_updatedDate": "2024-01-15T12:45:00.000Z",
 *   "status": "FAILED",
 *   "failureInfo": {
 *     "invalidRecords": ["INVALID_A_RECORD", "INVALID_CNAME_RECORD"],
 *     "invalidARecordInfo": {
 *       "expectedDnsRecords": [
 *         {
 *           "hostName": "example.com",
 *           "values": ["185.230.63.107", "185.230.63.108"]
 *         }
 *       ],
 *       "actualDnsRecords": [
 *         {
 *           "hostName": "example.com",
 *           "values": ["192.168.1.1"]
 *         }
 *       ]
 *     },
 *     "invalidCnameRecordInfo": {
 *       "expectedDnsRecords": [
 *         {
 *           "hostName": "www.example.com",
 *           "values": ["example.com.wixdns.net"]
 *         }
 *       ],
 *       "actualDnsRecords": [
 *         {
 *           "hostName": "www.example.com",
 *           "values": ["old-server.example.com"]
 *         }
 *       ]
 *     }
 *   },
 *   "dnsResolverIncludesWixNs": true
 * }
 */


import { createClient } from '@wix/sdk';
import { dnsPropagation } from '@wix/domains';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { dnsPropagation },
  // Include the auth strategy and host as relevant
});


async function getDnsPropagation(dnsPropagationId) {
  const response = await myWixClient.dnsPropagation.getDnsPropagation(dnsPropagationId);
};

Self-managed SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

Get Dns Propagation