From 022f1036798deb3efc164f9066f38422e6eba0be Mon Sep 17 00:00:00 2001
From: "rafael r. camargo" <66796237+rafaelrcamargo@users.noreply.github.com>
Date: Fri, 11 Sep 2026 20:27:51 -0300
Subject: [PATCH] docs(backend): clarify domain migration and deletion

---
 .changeset/two-aliens-build.md                  |  5 +++++
 packages/backend/src/api/endpoints/DomainApi.ts | 14 ++++++++------
 2 files changed, 13 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/two-aliens-build.md

diff --git a/.changeset/two-aliens-build.md b/.changeset/two-aliens-build.md
new file mode 100644
index 00000000000..ccdc6211572
--- /dev/null
+++ b/.changeset/two-aliens-build.md
@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Clarify domain API documentation for custom primary domain migration and the restriction on deleting the active domain.
diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts
index 4e66223048b..329c712e5f1 100644
--- a/packages/backend/src/api/endpoints/DomainApi.ts
+++ b/packages/backend/src/api/endpoints/DomainApi.ts
@@ -12,7 +12,7 @@ export type AddDomainParams = {
    * The new domain name. For development instances, can contain the port, e.g., `myhostname:3000`. For production instances, must be a valid FQDN, e.g., `mysite.com`. Cannot contain protocol scheme.
    */
   name: string;
-  /** Whether the new domain is a satellite domain. Only `true` is accepted at the moment. */
+  /** Whether the new domain is a satellite domain. Set to `false` to add the first custom primary domain to a production instance with an active provider domain. */
   is_satellite: boolean;
   /** The proxy URL for the domain. Applicable only to production instances. */
   proxy_url?: string | null;
@@ -40,7 +40,9 @@ export class DomainAPI extends AbstractAPI {
   }
 
   /**
-   * Adds a new domain to the instance. Useful in the case of multi-domain instances, allows adding [satellite domains](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) to an instance.
+   * Adds a [satellite domain](https://clerk.com/docs/guides/dashboard/dns-domains/satellite-domains) or the first custom primary domain to the instance.
+   *
+   * To migrate a production instance from an active provider domain to a custom primary domain, set `is_satellite` to `false`. The custom domain becomes active, and the provider domain remains attached. Additional custom primary domains are not supported.
    * @returns The created [`Domain`](https://clerk.com/docs/reference/backend/types/domain) object.
    */
   public async add(params: AddDomainParams) {
@@ -70,8 +72,8 @@ export class DomainAPI extends AbstractAPI {
   }
 
   /**
-   * Deletes a satellite domain for the instance. It is currently not possible to delete the instance's primary domain.
-   * @param satelliteDomainId - The ID of the satellite domain to delete.
+   * Deletes a domain for the instance. The active domain cannot be deleted.
+   * @param satelliteDomainId - The ID of the domain to delete.
    * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object).
    */
   public async delete(satelliteDomainId: string) {
@@ -79,8 +81,8 @@ export class DomainAPI extends AbstractAPI {
   }
 
   /**
-   * Deletes a satellite domain for the instance.
-   * @param satelliteDomainId - The ID of the satellite domain to delete.
+   * Deletes a domain for the instance. The active domain cannot be deleted.
+   * @param satelliteDomainId - The ID of the domain to delete.
    * @returns The [`DeletedObject`](https://clerk.com/docs/reference/backend/types/deleted-object).
    * @deprecated Use `delete()` instead.
    */