How to bundle domains into SaaS subscriptions with the name.com API

Bundling domain registration into a SaaS subscription eliminates the friction point where customers leave your product to register a domain at an external registrar, configure nameservers by hand, and return hoping it all worked. When the domain and the product feel like separate things, that's because they are, and that separation costs you onboarding confidence and customer time.

Riley & Grey solved this differently. The wedding website platform embedded domain registration directly into its subscription flow using the name.com API, so customers go from picking a domain to having a live site without touching a third-party registrar. Riley & Grey built the integration in days, and it has required minimal monthly maintenance over more than 12 years in production, including migrating to the latest version of the name.com API, Core.

This guide walks through the same four-stage pattern, covering domain discovery, registration, connecting the domain to your SaaS site, and ongoing lifecycle management alongside the subscription. All operations use core/v1 endpoints on our API, with your application coordinating domain operations with the customer's subscription lifecycle.

The four stages of domain provisioning

Mapping domain operations to subscription lifecycle events is what keeps the integration maintainable over time, producing a schedule determined by the customer lifecycle rather than by manual intervention.

Stage 1. Domain Discovery. When a customer is considering a paid plan that includes a custom domain, your app presents a search interface backed by our API. Customers search by keyword to find candidate domains, then check their availability and pricing before they commit to anything.

Stage 2. Registration. Once the customer picks a domain and completes payment, your subscription system triggers a registration call on their behalf. From the customer's perspective, the domain is part of what they bought, rather than a separate task.

Stage 3. Configuration. After registration, your app configures the domain to connect to your platform using the DNS or nameserver configuration appropriate to your architecture. This step happens during onboarding and completes the connection between the domain and the hosted product.

Stage 4. Lifecycle Management. As long as the subscription stays active, your system drives renewal. When the subscription is cancelled or expires, you decide whether to hold the domain for a grace period, transfer it, or release it.

Riley & Grey's integration demonstrates this pattern working at production scale. Mapping domain operations to subscription events is what produces that zero-maintenance outcome.

Authentication and sandbox setup

All requests to the name.com API use HTTP Basic Auth with your username and an API token. To generate tokens, go to Account Settings, then Security, then API Tokens. If 2FA is enabled on your account, you'll also need to toggle "name.com API Access" to on in those same Security settings before any token will work.

Generate two tokens, one for the sandbox and one for production. For sandbox calls, append -test to your username (so mycompany becomes mycompany-test) and point requests at https://api.dev.name.com. Production calls use your plain username and https://api.name.com.

The sandbox is the right place to run your full integration end to end before going live. Newly generated sandbox credentials can take up to 15 minutes to activate, and any domain you want to test operations on must first be registered in the sandbox. DNS records can be set there, but they won't resolve publicly. Switch to production credentials and the production API endpoint only after the complete four-stage flow works in the sandbox. Full credential instructions are in our documentation at docs.name.com.

Domain lifecycle implementation with the core API

Stage 1. Domain discovery

The POST /core/v1/domains:search endpoint accepts a keyword and returns available domain candidates with pricing. Use POST /core/v1/domains:checkAvailability when you want to verify specific domain names directly, checking up to 50 names at a time.

Both endpoints return a SearchResponse containing results with the relevant domain information. Set purchaseType to "registration" to keep the search focused on standard registrations with predictable pricing and immediate fulfillment. Domains with a different purchaseType may involve backorder or auction flows that don't fit an automated provisioning pattern.

// Stage 1: Search for domain candidates by keyword
const searchResponse = await fetch(
  'https://api.dev.name.com/core/v1/domains:search',
  {
    method: 'POST',
    headers: {
      // Base64-encode "username:token" for Basic Auth
      'Authorization': `Basic ${btoa('mycompany-test:sandbox-token')}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      keyword: 'acmeflowers',
      purchaseType: 'registration',
    }),
  }
);

// Response excerpt, with the fields your UI needs
// {
//   "results": [
//     {
//       "domainName": "acmeflowers.com",
//       "purchasable": true,
//       "purchaseType": "registration",
//       "purchasePrice": 12.99,
//       "premium": false
//     }
//   ]
// }

Only surface results where purchasable is true and purchaseType equals "registration". Display purchasePrice so customers see the cost before they pick.

Stage 2. Registration

Once the customer completes checkout, register the domain with POST /core/v1/domains. You can provide nameservers as part of the registration request, allowing registration and initial domain configuration to happen together. If the nameservers need to be changed after registration, use POST /core/v1/domains/{domainName}:setNameservers.

// Stage 2: Register the domain when the subscription is created
const registerResponse = await fetch(
  'https://api.dev.name.com/core/v1/domains',
  {
    method: 'POST',
    headers: {
      // Base64-encode "username:token" for Basic Auth
      'Authorization': `Basic ${btoa('mycompany-test:sandbox-token')}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      domain: {
        domainName: 'acmeflowers.com',
        nameservers: ['ns1.yourplatform.com', 'ns2.yourplatform.com'],
      },
    }),
  }
);

// On success (HTTP 200), immediately persist the domainName
// alongside customer_id and subscription_id in your database.
// Every downstream operation depends on this association.

Write the domain-to-subscription association to your database before responding to the customer. Configuration, renewal, and webhook handling all require a reliable way to look up which domain belongs to which account.

Stage 3. Domain configuration

If you didn't pass nameservers during registration, set them now with POST /core/v1/domains/{domainName}:setNameservers. If you need to change them later, you can use the same endpoint. Nameservers should already be configured and hosting the zone before you make this request. Then create the DNS records your platform routing requires.

// Stage 3: Create a CNAME record pointing to your platform
const dnsResponse = await fetch(
  'https://api.dev.name.com/core/v1/domains/acmeflowers.com/records',
  {
    method: 'POST',
    headers: {
      // Base64-encode "username:token" for Basic Auth
      'Authorization': `Basic ${btoa('mycompany-test:sandbox-token')}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'CNAME',
      host: 'www',
      answer: 'sites.yourplatform.com',
      ttl: 300, // 300 seconds is the minimum TTL
    }),
  }
);

// For an apex (root domain) record, set host to "" or "@"

Stage 4. Renewal

Renewal fires from your subscription billing system on the customer's billing date. The POST /core/v1/domains/{domainName}:renew endpoint extends the registration by a given number of years. For premium domains, retrieve the current renewalPrice for the requested number of years and pass it as purchasePrice. Standard, non-premium renewals don't require purchasePrice.

// Stage 4: Renew the domain when the subscription billing cycle fires
const renewResponse = await fetch(
  'https://api.dev.name.com/core/v1/domains/acmeflowers.com:renew',
  {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('mycompany-test:sandbox-token')}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      purchaseYears: 1,
      //Premium domain:add purchasePrice from GET /core/v1/domains/{domainName}:getPricing
    }),
  }
);

Tying the domain to the subscription pays off at renewal. Your billing event fires, your code looks up the domain by subscription_id, and our API extends the registration without requiring the customer to renew it manually.

How to keep domain and subscription state in sync

Subscription events driving domain operations covers the outbound side. Webhooks from the name.com API cover the inbound side, and you need both to keep state consistent.

Subscribe to domain events with POST /core/v1/notifications. The events worth subscribing to in a SaaS subscription context are domain.registry.rejection, which can interrupt provisioning if a registration is rejected by the registry, domain.expiration, which indicates that a domain has expired and entered its post-expiry grace period, and account.domain.removal, which indicates that a domain has been removed from the account.

// Subscribe to a domain lifecycle event
const notificationResponse = await fetch(
  'https://api.dev.name.com/core/v1/notifications',
  {
    method: 'POST',
    headers: {
      // Base64-encode "username:token" for Basic Auth
      'Authorization': `Basic ${btoa('mycompany-test:sandbox-token')}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      eventName: 'domain.registry.rejection',
      url: 'https://yourplatform.com/webhooks/domain',
      active: true,
    }),
  }
);

Subscribe separately to each event you want to receive. Our webhook payloads include the domain name. Your handler needs to resolve that domain name back to the customer and subscription it belongs to, which is why writing the domain-to-subscription association at registration time is the right move. Without that lookup table, our webhooks arrive as orphaned events with no way to act on them.

Test the full webhook loop in the sandbox before going to production. Subscribe to the relevant events, trigger the applicable domain state changes, confirm your handler resolves each notification to the correct customer record, and verify your server returns the expected response.

Start building

This pattern treats domains as a feature of your product rather than an external task handed off to customers. You find a domain for them, register it when they subscribe, connect it to their site during onboarding, and renew it automatically while they keep paying, so the domain stays inside your product lifecycle from day one.

Riley & Grey's integration shows that this approach can hold up over time. The team built its embedded domain experience in a single day, and it has required zero monthly maintenance over more than 12 years in production.

Start in the sandbox, run the complete lifecycle end to end, then switch your credentials to production. Our sandbox uses the same API structure as production without real charges, making it the right place to validate your integration before launch. Get started with the name.com Core API documentation and, if you need custom pricing or direct access to the name.com product and engineering teams, reach out to the partnerships team.