> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # UpsertDomainAssignment # Package: domains # Namespace: DomainAssignmentService # Method link: https://dev.wix.com/docs/api-reference/account-level/domains/domain-assignments/upsert-domain-assignment.md ## Permission Scopes: Manage Domains: SCOPE.ACC-DC-PREMIUM.MANAGE-DOMAINS ## Introduction Assigns a domain to a site, or moves the domain from a different site. Upsert Domain Assignment creates or updates the domain assignment based on the domain's current state: + Domain isn't assigned: Creates a domain assignment. + Domain is assigned to the specified site: Returns the existing domain assignment unchanged, even if you specify a different `assignmentType`. To make the domain the site's primary domain, call [Set Domain As Primary](https://dev.wix.com/docs/api-reference/account-level/domains/domain-assignments/set-domain-as-primary.md). + Domain is a redirect on a different site: Removes the domain from that site and assigns it to the specified site. + Domain is the primary domain of a different site: Fails. To move the domain, first call Set Domain As Primary to make a different domain that site's primary domain. The site must have a Premium plan. When you assign a domain as `PRIMARY` to a site that already has domain assignments, the site's existing domain assignments are removed, including its previous primary domain and all redirects. To keep them, assign the domain as `REDIRECT`, and then call Set Domain As Primary. When you assign a domain as `REDIRECT` to a site that has no domain assignments, the domain becomes the site's primary domain. You must specify the Wix account ID in the `wix-account-id` header. --- ## REST API ### Schema ``` Method: upsertDomainAssignment Description: Assigns a domain to a site, or moves the domain from a different site. Upsert Domain Assignment creates or updates the domain assignment based on the domain's current state: + Domain isn't assigned: Creates a domain assignment. + Domain is assigned to the specified site: Returns the existing domain assignment unchanged, even if you specify a different `assignmentType`. To make the domain the site's primary domain, call [Set Domain As Primary](https://dev.wix.com/docs/api-reference/account-level/domains/domain-assignments/set-domain-as-primary.md). + Domain is a redirect on a different site: Removes the domain from that site and assigns it to the specified site. + Domain is the primary domain of a different site: Fails. To move the domain, first call Set Domain As Primary to make a different domain that site's primary domain. The site must have a Premium plan. When you assign a domain as `PRIMARY` to a site that already has domain assignments, the site's existing domain assignments are removed, including its previous primary domain and all redirects. To keep them, assign the domain as `REDIRECT`, and then call Set Domain As Primary. When you assign a domain as `REDIRECT` to a site that has no domain assignments, the domain becomes the site's primary domain. You must specify the Wix account GUID in the `wix-account-id` header. URL: https://www.wixapis.com/domains/v1/domain-assignments/upsert/domain/{domainAssignment.domain} Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: domainAssignment, domainAssignment.domain, domainAssignment.siteInfo.assignmentType Method parameters: param name: domainAssignment | type: DomainAssignment | description: A domain assignment connects a domain to a Wix site, either as the site's primary domain or as a redirect to the site's primary domain. A domain can be assigned to 1 site at a time, and each site has a single primary domain. | required: true - name: domain | type: string | description: Domain name, including the top-level domain. For example, `mystunningsite.com`. | required: true | validation: format HOSTNAME - name: siteInfo | type: SiteInfo | description: Site the domain is assigned to, and whether the domain is the site's primary domain or a redirect. - name: id | type: string | description: GUID of the site the domain is assigned to. Required unless the request header specifies the site GUID. If you specify the site GUID in both places, the GUIDs must be identical. | validation: format GUID - name: assignmentType | type: AssignmentType | description: Whether the domain is the site's primary domain or a redirect to the site's primary domain. | required: true - enum: - PRIMARY: Site's primary domain. Visitors who enter this domain reach the site directly. - REDIRECT: Domain that redirects visitors to the site's primary domain. A site can have up to 300 redirect domains. Return type: UpsertDomainAssignmentResponse - name: domainAssignment | type: DomainAssignment | description: Created, updated, or existing domain assignment. - name: id | type: string | description: Domain assignment GUID. Identical to `domain`. | read-only: true | validation: format HOSTNAME - name: domain | type: string | description: Domain name, including the top-level domain. For example, `mystunningsite.com`. | validation: format HOSTNAME - name: siteInfo | type: SiteInfo | description: Site the domain is assigned to, and whether the domain is the site's primary domain or a redirect. - ONE-OF: - name: redirectInfo | type: RedirectAssignmentInfo | description: Redirect details. Returned only when `assignmentType` is `REDIRECT`. | read-only: true - name: primaryDomain | type: string | description: Primary domain that this domain redirects to. | read-only: true | validation: format HOSTNAME - name: id | type: string | description: GUID of the site the domain is assigned to. Required unless the request header specifies the site GUID. If you specify the site GUID in both places, the GUIDs must be identical. | validation: format GUID - name: assignmentType | type: AssignmentType | description: Whether the domain is the site's primary domain or a redirect to the site's primary domain. - enum: - PRIMARY: Site's primary domain. Visitors who enter this domain reach the site directly. - REDIRECT: Domain that redirects visitors to the site's primary domain. A site can have up to 300 redirect domains. - name: createdDate | type: string | description: Date and time the domain assignment was created. | read-only: true | validation: format date-time - name: updatedDate | type: string | description: Date and time the domain assignment was last updated. | read-only: true | validation: format date-time Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: DOMAIN_IS_PRIMARY_ON_ANOTHER_SITE | Description: The domain is the primary domain of a different site. To move it, first call [Set Domain As Primary](https://dev.wix.com/docs/api-reference/account-level/domains/domain-assignments/set-domain-as-primary.md) to make a different domain that site's primary domain. ``` ### Examples ### Assign a domain to a site as a redirect Assigns a domain to a site as a redirect to the site's primary domain. ```curl curl -X POST \ 'https://www.wixapis.com/domains/v1/domain-assignments/upsert/domain/mystunningsite.net' \ -H 'wix-account-id: ' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "domainAssignment": { "domain": "mystunningsite.net", "siteInfo": { "id": "d7a341c4-196b-46e7-813c-2b0fc1847ec6", "assignmentType": "REDIRECT" } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.domains.domainAssignments.upsertDomainAssignment(domain, domainAssignment) Description: Assigns a domain to a site, or moves the domain from a different site. Upsert Domain Assignment creates or updates the domain assignment based on the domain's current state: + Domain isn't assigned: Creates a domain assignment. + Domain is assigned to the specified site: Returns the existing domain assignment unchanged, even if you specify a different `assignmentType`. To make the domain the site's primary domain, call [Set Domain As Primary](https://dev.wix.com/docs/api-reference/account-level/domains/domain-assignments/set-domain-as-primary.md). + Domain is a redirect on a different site: Removes the domain from that site and assigns it to the specified site. + Domain is the primary domain of a different site: Fails. To move the domain, first call Set Domain As Primary to make a different domain that site's primary domain. The site must have a Premium plan. When you assign a domain as `PRIMARY` to a site that already has domain assignments, the site's existing domain assignments are removed, including its previous primary domain and all redirects. To keep them, assign the domain as `REDIRECT`, and then call Set Domain As Primary. When you assign a domain as `REDIRECT` to a site that has no domain assignments, the domain becomes the site's primary domain. You must specify the Wix account GUID in the `wix-account-id` header. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: domainAssignment, domain, domainAssignment.siteInfo.assignmentType Method parameters: param name: domain | type: string | description: Domain name, including the top-level domain. For example, `mystunningsite.com`. | required: true | validation: format HOSTNAME param name: domainAssignment | type: DomainAssignment | description: A domain assignment connects a domain to a Wix site, either as the site's primary domain or as a redirect to the site's primary domain. A domain can be assigned to 1 site at a time, and each site has a single primary domain. | required: true - name: domain | type: string | description: Domain name, including the top-level domain. For example, `mystunningsite.com`. | validation: format HOSTNAME - name: siteInfo | type: SiteInfo | description: Site the domain is assigned to, and whether the domain is the site's primary domain or a redirect. - name: _id | type: string | description: GUID of the site the domain is assigned to. Required unless the request header specifies the site GUID. If you specify the site GUID in both places, the GUIDs must be identical. | validation: format GUID - name: assignmentType | type: AssignmentType | description: Whether the domain is the site's primary domain or a redirect to the site's primary domain. | required: true - enum: - PRIMARY: Site's primary domain. Visitors who enter this domain reach the site directly. - REDIRECT: Domain that redirects visitors to the site's primary domain. A site can have up to 300 redirect domains. Return type: PROMISE - name: domainAssignment | type: DomainAssignment | description: Created, updated, or existing domain assignment. - name: _id | type: string | description: Domain assignment GUID. Identical to `domain`. | read-only: true | validation: format HOSTNAME - name: domain | type: string | description: Domain name, including the top-level domain. For example, `mystunningsite.com`. | validation: format HOSTNAME - name: siteInfo | type: SiteInfo | description: Site the domain is assigned to, and whether the domain is the site's primary domain or a redirect. - ONE-OF: - name: redirectInfo | type: RedirectAssignmentInfo | description: Redirect details. Returned only when `assignmentType` is `REDIRECT`. | read-only: true - name: primaryDomain | type: string | description: Primary domain that this domain redirects to. | read-only: true | validation: format HOSTNAME - name: _id | type: string | description: GUID of the site the domain is assigned to. Required unless the request header specifies the site GUID. If you specify the site GUID in both places, the GUIDs must be identical. | validation: format GUID - name: assignmentType | type: AssignmentType | description: Whether the domain is the site's primary domain or a redirect to the site's primary domain. - enum: - PRIMARY: Site's primary domain. Visitors who enter this domain reach the site directly. - REDIRECT: Domain that redirects visitors to the site's primary domain. A site can have up to 300 redirect domains. - name: _createdDate | type: Date | description: Date and time the domain assignment was created. | read-only: true - name: _updatedDate | type: Date | description: Date and time the domain assignment was last updated. | read-only: true Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: DOMAIN_IS_PRIMARY_ON_ANOTHER_SITE | Description: The domain is the primary domain of a different site. To move it, first call [Set Domain As Primary](https://dev.wix.com/docs/api-reference/account-level/domains/domain-assignments/set-domain-as-primary.md) to make a different domain that site's primary domain. ``` ### Examples ### Assign a domain to a site as a redirect Assigns a domain to a site as a redirect to the site's primary domain. ```javascript import { domainAssignments } from "@wix/domains"; async function upsertDomainAssignment() { const response = await domainAssignments.upsertDomainAssignment( "mystunningsite.net", { siteInfo: { id: "d7a341c4-196b-46e7-813c-2b0fc1847ec6", assignmentType: "REDIRECT", }, }, ); } /* Promise resolves to: * { * "domainAssignment": { * "_id": "mystunningsite.net", * "domain": "mystunningsite.net", * "siteInfo": { * "id": "d7a341c4-196b-46e7-813c-2b0fc1847ec6", * "assignmentType": "REDIRECT", * "redirectInfo": { * "primaryDomain": "mystunningsite.com" * } * }, * "_createdDate": "2026-11-01T10:30:00.000Z", * "_updatedDate": "2026-11-01T10:30:00.000Z" * } * } */ ``` ### upsertDomainAssignment (self-managed) 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.md). ```javascript import { createClient } from '@wix/sdk'; import { domainAssignments } from '@wix/domains'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { domainAssignments }, // Include the auth strategy and host as relevant }); async function upsertDomainAssignment(domain,domainAssignment) { const response = await myWixClient.domainAssignments.upsertDomainAssignment(domain,domainAssignment); }; ``` ---