Assign Domain

Changes which site a domain in the account serves, and in which role. A site has one primary domain (the address visitors land on) and up to 300 redirects (domains that send visitors to the primary domain). A domain is on one site at a time, or on none.

Every call runs in the user's own context, as the signed-in user, at account scope. No API key or integration token. The account ID header is added for you.

Flow

1. Normalize the domain: lowercase, trim, strip http://, https://, www. and any path. No domain named ("connect a domain I own to my site") → the whole reply is: "What domain would you like to connect?" Nothing can be read or changed without the domain, so this is the answer even when you would otherwise go ahead on assumptions. Don't ask for the site or the role (the read settles those later), don't send any link (no My Domains, no domain settings), don't read another skill, and don't say that nothing was changed.
2. Know the target site, when the request has one (connect, move, change role). Take it from the site context ("this site"), from the conversation, or by name as Query Sites describes. When several sites match, or none was named and the domain is on no site, list the account's sites by name and ask which one. Taking a domain off its site, or connecting it or changing its role with no site named, needs no target up front: pass null. When the read shows the domain on a site, that site is X for taking it off, and T for anything else (so a domain already there gets the Already answer). Ask which site only when the domain is on no site.
3. Read the state (next section), silently, in one call.
4. Pick the row in the decision table that fits the state and the request.
5. Check the gate against that row's writes. Any condition unmet → no write; the gate table says what to answer instead. All met → send the row's offer and end your turn.
6. Only after an explicit yes to that offer, run the writes, in one call, and report in one sentence.

Run each script below as one call, with whatever lets you run a short script over several Wix API requests at once. Do not split it into separate requests. Never name an endpoint, field, enum value, error code or tool to the user, and never narrate the calls ("let me check", "running the update").

Read the state

One read-only call. Put the domain in domain, the target site's ID in targetSiteId, or null when no site was named (taking the domain off its site, or a role change on the site it is on), and the Account ID from the Wix context you already read in accountId.

What comes back, verified live:

A domain on no site and a domain that is not in the account both answer "not found" to the assignment lookup; the domain view and the connected domain tell them apart. The domain view answers for a domain in the account and 404 for any other, but it has also answered 404 for a domain connected from elsewhere that was in the account, so a domain-view 404 is followed by the connected-domain lookup, which answers for every domain connected from elsewhere. For a domain another account holds, that lookup answers 403 with DOMAIN_NOT_PERMITTED: that too means "not in this account", not a failed read. The domain view's first attempt can fail on a missing call scope, so it is tried twice. All of this happens inside the one call: never look the domain up again in a separate call, and never search the docs for another way to find it.

The gate

All four must hold before any write. Check them in this order:

Free-site answer — the target site has no Premium plan:

{upgrade URL} is https://manage.wix.com/premium-pricing/studio/select-plan?siteGuid={siteId} when the site's editorType is STUDIO, otherwise https://manage.wix.com/premium-pricing/sunrise/select-plan?siteGuid={siteId}. The block is the same fixed copy Domain Search, Purchase and Connect uses: do not reword it, and never promise to put the domain on the site once they upgrade.

Decision table

{domain} is the domain the user named. T is the target site, {T} its name, {T primary} its primary domain. X is the site the domain is on now, {X} its name. {R} is a redirect on the site being changed.

"Assign" is always as a redirect. On a site with no domains, a redirect becomes the primary domain; on a site that has one, promoting afterwards makes it primary and turns the old primary into a redirect. Assigning straight in as primary would remove every domain the site already has.

When the user asks for a role on a site with no domains, there is nothing to redirect to: the domain becomes its primary domain, and the offer says so.

When a site has several redirects and the row says "the {R} the user picks", list them by name in the offer and let the user choose. With exactly one, name it and ask for a yes.

Offer copy

Two dashboard links are used in this skill, and only in three places: the failed-read row in Read the state, the "no / I'll do it myself" row in Reading the answer, and On failure under Run the writes. Send one only there, never as a fallback of your own. Their URLs are owned by Domains Dashboard Navigation; take them from there:

• {domain settings link}: the site's domain settings, labelled Domain settings for {site name}.
• {My Domains link}: the account's domain list, labelled My Domains.

Every offer is one message and ends the turn. Show every domain in full. Say primary domain and redirect; never "main address", "main domain" or "main URL", even when the user does.

A1 — target site has no domains:

A2 — target site has a primary domain, no role asked for:

A3 — redirect asked for:

P1 — replaces a live primary domain:

P2 — demote the primary domain:

Only — the site's only domain:

M1 — move a redirect:

M2 — move a primary domain whose site has redirects:

M3 — move a site's only domain:

T's role — the end of every move offer, picked by what T has and what the user asked:

U1 — take a redirect off:

U2 — take a primary domain off a site that has redirects:

U3 — take the only domain off:

Already:

Off:

Reading the answer

Run the writes only when every choice the offer left open — {R} and the role on T — has an answer. If one is still open, ask only for that one and end the turn.

Silence, a repeated request or "whatever you think" is not a yes.

Run the writes

One call, after the yes. List the row's writes in steps, in order. Each step is retried once; the first step that still fails stops the call, and the result says which steps ran.

assign and promote answer with the domainAssignment; siteInfo.assignmentType is the role the domain holds now (PRIMARY after assigning to a site with no domains). unassign answers {}. assign to the site a domain is already on changes nothing, whatever role you send: a role change is always promote. promote on a domain that is already primary changes nothing either. assign on a domain that is another site's primary domain fails, which is why M2 and M3 free it first.

Report

One sentence, from what done shows. Nothing about timing, DNS, SSL or propagation, and nothing about what a site that lost a domain shows now.

On failure, say what did change, then hand over the dashboard, without naming the error:

When primaryElsewhere is true, the domain became another site's primary domain after the read. Read the state again and send M2 or M3. Do not offer the same write a third time unless the user asks.

Never

• Write anything before the user's yes to an offer that named every change. A yes to "move it" is not a yes to replacing a primary domain the offer did not name.
• Assign a domain as PRIMARY. Assign as a redirect, then promote.
• Unassign a site's primary domain while the site has redirects, unless the user asked to remove every domain from that site and the offer named them all.
• Write a domain that neither the read nor the calling skill found in the account, on the user's word or on its root domain's.
• Assign a domain to a site without a Premium plan.
• Guess a role, or which redirect to promote.
• Say what happens to a site after it loses a domain: no "it goes back to its Wix address", no "your other domain takes over".
• Promise timing, propagation, SSL, or "up to 48 hours", or explain DNS, nameservers or records.
• Look up who owns a domain.
• Say "main address", "main domain" or "main URL" for primary domain.

Next steps

• Buying a domain, or bringing one in from another registrar: Domain Search, Purchase and Connect.
• Expiry, renewal, DNS or SSL state of a domain: Analyse Domain.
• Official reference: Domain Assignments, and its sample flows.