1. GWS
ResellerStack Developer API
  • Introduction
  • Quick start
  • API Reference
    • Customers
      • List customers
      • Create customer
      • Get customer
      • Update customer notes
      • Update customer status
      • Update billing details
    • Geo
      • List countries
      • List states
    • Pricing
      • List TLD pricing
      • Update TLD pricing
      • Set TLD featured
      • Apply bulk margin
      • Reorder TLD pricing
    • Domains
      • List domains
      • Check domain availability
      • Register a domain
      • Checkout domain cart (bulk)
      • Toggle WHOIS privacy
      • Update domain contacts
      • Get domain
      • Toggle transfer lock
      • Toggle auto-renew
      • Preview renewal price
      • Renew domain now
      • Register a domain with Google Workspace
      • List bundle offers for a name
      • Register a bundle
    • Contacts
      • List contacts
      • Create contact
      • Get contact
    • Orders
      • List orders
      • Get order
    • DNS
      • List DNS records
      • Add DNS records
      • Update DNS record
      • Delete DNS record
      • Update nameservers
      • Reset nameservers
      • List DNSSEC records
      • Add DNSSEC record
      • Delete DNSSEC record
    • Wallet
      • Get wallet balance
    • Webhooks
      • workspace.pastdue
      • workspace.expired
      • workspace.txt.failed
      • workspace.renewed
      • workspace.provisioned
      • workspace.txt.ready
      • workspace.txt.propagated
      • workspace.licenses.increased
      • workspace.deleted
      • workspace.failed
      • mailbox.ready
      • mailbox.deleted
      • workspace.dkim.ready
      • workspace.dkim.propagated
      • workspace.domain.swapped
      • Delivered when domain.order.success fires
      • Delivered when domain.order.failed fires
      • Delivered when domain.renewal.success fires
      • Delivered when domain.renewal.failed fires
    • GWS
      • Google Workspace ~ Creation Flow
      • Google Workspace ~ Sandbox Environment
      • Check Workspace Exists
        POST
      • Create Workspace
        POST
      • List Workspaces
        GET
      • Delete Workspace
        DELETE
      • Check DNS Propagation
        POST
      • Renew Workspace
        POST
      • Change Primary Domain (Beta)
        POST
    • Licenses & Mailboxes
      • Create Mailbox
      • List Mailboxes
      • Delete Mailboxes
      • Decrease Seats
  • Health check
    GET
  • Get current partner
    GET
  1. GWS

Change Primary Domain (Beta)

Production
https://api.resellerstack.ai/api/v1
Production
https://api.resellerstack.ai/api/v1
POST
/gws/primary-domain
🧪 Beta, sandbox only for now. This endpoint is in beta: it is available in the sandbox environment only, its behaviour may change, and live access is coming soon.
Swap a Google Workspace's primary domain (current_domain → new_domain).

Requirements#

The new domain must already be added to Google Workspace and owned by the same customer.
The request must use the correct userId.
The endpoint is currently available only in the sandbox environment.

What Happens When You Change the Primary Domain?#

1.
Domain verification: Verify ownership of the new domain by adding the required TXT record to its DNS settings.
2.
DKIM configuration: A new DKIM key is generated for the new domain. Publish the new DKIM record in DNS and wait for it to propagate.
3.
Email DNS configuration: Configure the new domain's MX and SPF records to support email delivery and sender authentication.
4.
Mailbox transition: Existing mailboxes are preserved under the old domain and marked as swapped. New mailbox records are created for the new domain with an initial status of IN_PROGRESS.
5.
Activation: New mailboxes transition to ACTIVE once the required verification and DKIM checks are complete.

DNS Records to Configure#

When switching to a new primary domain, configure the necessary DNS records for the new domain.
TXT verification record: Add the verification TXT record provided for the new domain to prove domain ownership.
DKIM record: Publish the new DKIM public key provided for the new domain. The old domain's DKIM key should not be reused unless explicitly supported.
MX records: Configure the new domain's MX records to route incoming email to Google Workspace.
SPF record: Configure the new domain's SPF TXT record to authorize the appropriate email-sending servers. If an SPF record already exists, update it instead of creating multiple SPF records.
Note: DNS records from the old domain do not automatically transfer to the new domain. Configure the new domain independently. Keep the old domain's DNS records if it must continue receiving or sending email.

Tracking Progress#

The API returns 202 Accepted, meaning the request has been accepted and processing will continue in the background. It does not mean the domain swap is complete.
Use the following webhooks to monitor progress:
WebhookDescription
workspace.txt.readyThe domain verification TXT record is ready.
workspace.txt.propagatedThe verification TXT record has propagated.
workspace.domain.swappedThe primary domain swap has completed.
workspace.dkim.readyThe DKIM record is ready.
workspace.dkim.propagatedThe DKIM record has propagated.
mailbox.readyA mailbox is ready.
Each webhook includes for_primary_domain_swap: true to identify events associated with the primary domain swap.

If the DNS of the domain is managed by you#

1.
Add the verification TXT record provided for the new domain.
2.
Call POST /dns-propagation-checks to resume domain verification.
3.
Add the new DKIM record when it becomes available.
4.
Call POST /dns-propagation-checks again to resume DKIM verification.
5.
Ensure the new domain's MX and SPF records are configured correctly.
A separate propagation check is required for the verification TXT record and DKIM.

Example#

POST /gws/primary-domain
{
  "userId": "b3d6f2a1-4c8e-4f9d-a2b1-7e3d5c9f0a12",
  "current_domain": "example.com",
  "new_domain": "example.org"
}

Request

Authorization
API Key
Add parameter in header
rs-x-api-key
Example:
rs-x-api-key: ********************
or
Body Params application/jsonRequired

Examples

Responses

🟢202Accepted
application/json
Swap queued; runs in the background.
Bodyapplication/json

🟠400Bad Request
🟠403Forbidden
🟠404Not Found
🟠409Conflict
🟠422Validation Error
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.resellerstack.ai/api/v1/gws/primary-domain' \
--header 'rs-x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "b3d6f2a1-4c8e-4f9d-a2b1-7e3d5c9f0a12",
    "current_domain": "example.com",
    "new_domain": "example.org"
}'
Response Response Example
202 - Example 1
{
    "status": 202,
    "message": "Primary domain swap queued",
    "data": {
        "swapId": "d81c7a2e-9b3f-4a6c-8e21-5f0b2c7d1a93",
        "status": "QUEUED"
    }
}
Modified at 2026-10-22 09:07:25
Previous
Renew Workspace
Next
Create Mailbox
Built with