Clarify subdomain domain changes

[SarahSoutoul]

Preview

• https://clerk.com/docs/pr/ss-docs-11756/guides/development/deployment/changing-domains

What does this solve?

A customer was trying to move their production app from a root domain to a subdomain of that same root domain and used the Change domain flow in the Dashboard. The current guide was confusing because it didn't explain how subdomain moves work in this flow or what Primary application vs Secondary application means when selecting the new domain type.

This update keeps the guide focused on changing a production domain, while clarifying that moves like example.com -> app.example.com can still be made from the Domains page and require choosing the correct application type. It also explains that Secondary application refers to the type of domain being added, not whether that domain will remain secondary after the change.

What changed

• Renames the guide from Change domain or subdomain to Change domain
• Updates the guide description and intro to focus on the production domain change flow
• Adds clarification for moves like example.com -> app.example.com
• Documents when to choose Primary application vs Secondary application
• Clarifies that a subdomain selected as Secondary application can still become the instance’s primary domain after the change

Linear ticket

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	May 29, 2026 4:57pm

[alexisintech]

I'm not seeing this primary vs secondary application nomenclature or flow in the clerk dashboard, nor clerk staging. let's hop on a quick call!

[SarahSoutoul]

I'm not seeing this primary vs secondary application nomenclature or flow in the clerk dashboard, nor clerk staging. let's hop on a quick call!

Here is a screenshot but yeah we can jump on a call @alexisintech