Building a domain storefront with the name.com API

Railway built its in-product domain integration with one product engineer in roughly two weeks. Within its first quarter, users were purchasing more than 1,700 domains per month. The implementation was fully self-serve, with the team building against the API even before contacting name.com as launch approached.

Platforms that redirect users to an external registrar at checkout hand off the conversion moment. The user lands somewhere else, gets distracted, and may register with a different account. The relationship frays before it's established.

This guide walks through building a domain storefront using the name.com API, following the official Reseller MVP Flow of Search, Register, and Manage. For storefronts that need high-throughput discovery, it also shows where Zone Check fits as an optional discovery optimization. All of the endpoints in this guide use the name.com Core API.

Credentials and environments

The name.com API uses HTTP Basic Auth with your username as the username and your API token as the password. Start by creating a name.com account with a dedicated, company-wide username, one that doesn't depend on Google SSO. SSO-based usernames cause friction when you need a stable credential tied to a service account rather than a person.

Once you have an account, navigate to Account Settings, then Security, then API Tokens to generate separate credentials for production (api.name.com) and the sandbox (api.dev.name.com). The credentials are environment-specific, so your production token won't work against the sandbox, and vice versa. If you have 2FA enabled on the account, you'll also need to toggle name.com API Access on within the Security settings before any API request will succeed.

For the sandbox, append -test to your regular username. If your production username is reseller123, your sandbox username is reseller123-test. Newly generated sandbox credentials can take up to 15 minutes to activate, so generate them before you need them.

On the SDK side, official clients are available for TypeScript, Go and PHP. If your team prefers generating a typed client from scratch, the Core API ships an OpenAPI 3.1 spec in YAML format. Download it from the API docs and run it through your code generator of choice.

Before going further, verify that authentication and environment routing are configured correctly:

# Verify credentials against the sandbox
curl -u "reseller123-test:YOUR_SANDBOX_TOKEN" \
  https://api.dev.name.com/core/v1/hello

# A successful response returns your username and confirms the environment is reachable

If this call returns a 401, recheck the username suffix and confirm the token was generated for the development environment.

Search layer design

A domain storefront runs two distinct operations, discovery and purchase-time confirmation. The domains:search endpoint handles discovery. domains:checkAvailability handles the moment just before a user buys. Treating them as the same operation can lead to incorrect assumptions, because availability and pricing can change between the two calls, which means search results reflect discovery pricing, not a registration guarantee.

Discovery with POST /core/v1/domains:search

For an MVP, scope your search requests to purchaseType: "registration". This filters results to domains available for immediate, standard registration, with no aftermarket flows or auction paths to handle before you've validated the core experience.

// POST https://api.dev.name.com/core/v1/domains:search
{
  "keyword": "acmecoffee",
  "purchaseType": "registration",
  "tldFilter": ["com", "net", "co", "io"]
}

The response includes the fields you need to populate search results, including purchasePrice, renewalPrice, premium (boolean), and purchasable. Display purchasePrice and renewalPrice together. Users who see a low registration price and then encounter a high renewal cost at checkout will drop off. Surface premium: true domains clearly because they require a different pricing confirmation path before registration.

Optional zone check for high-throughput discovery

If your storefront needs to screen large numbers of candidate domains quickly, for example a search-as-you-type experience across hundreds of TLDs, POST /core/v1/domains:zoneCheck is an optional optimization. It uses cached zone-file data to provide a fast screening result without making a live registry availability check.

// POST https://api.dev.name.com/core/v1/domains:zoneCheck
// Use for fast pre-screening only, not authoritative
{
  "domainNames": [
    "acmecoffee.com",
    "acmecoffee.io",
    "acmecoffee.co",
    "acmecoffee.net"
  ]
}

Zone Check can report a domain as taken when it's actually available (false positive), but it won't report an unavailable domain as available (no false negatives). Use it as an optional discovery path for high-throughput screening, not as a replacement for domains:search or the authoritative checkAvailability step before purchase.

Purchase-time gate with POST /core/v1/domains:checkAvailability

Before calling “Create Domain”, always re-check the selected domain with domains:checkAvailability. This is the authoritative check. It confirms current availability and returns the exact purchasePrice and purchaseType you'll need to pass into the registration request. By the time a user clicks buy, availability may have changed from what search results showed.

Domain registration

A successful “Check Availability” response gives you everything you need to build the “Create Domain” request. Pass purchaseType directly from that response rather than hardcoding it. For a registration-only MVP, you can scope this to "registration", but copying the value from the check result keeps the registration request aligned with the selected purchase type.

// POST https://api.dev.name.com/core/v1/domains
// Standard (non-premium) registration
{
  "domainName": "acmecoffee.com",
  "purchaseType": "registration",
  "years": 1
  // purchasePrice omitted for standard registrations
}

For premium domains, the rules are stricter. Include purchasePrice with the exact value returned by “Check Availability”. If the supplied price doesn't match what the API expects at registration time, the request fails.For standard registrations, purchasePrice can be omitted. If you do supply a price, it must match the API's current price. . Get the value from checkAvailability immediately before the create call, not from an earlier search result.

Always include X-Idempotency-Key on “Create Domain” requests. Network timeouts happen, and a retry without this header can cause the same operation to be submitted more than once. Set the value to a UUID generated at the start of the checkout flow and reuse it for any retries:

curl -u "reseller123-test:YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -X POST https://api.dev.name.com/core/v1/domains \
  -d '{"domainName": "acmecoffee.com", "purchaseType": "registration", "years": 1}'

Some TLDs require additional registration data. Country-code domains in particular often need registrant eligibility fields. Check the TLD requirements endpoint for each TLD in your supported list before launch. If a TLD returns required fields you haven't collected, exclude it from your storefront rather than letting users hit a registration failure at checkout.

Treat a failed “Create Domain” response as non-deterministic. A domain that passed “Check Availability” a few seconds earlier may have been registered by someone else in the window between checks. Your error handling should surface this gracefully and invite the user to search again.

You should also implement error handling. “Create Domain” can fail even after a successful availability check because the domain or its pricing may have changed. Handle the API's error response explicitly, log the returned error details for diagnosis, and avoid blindly retrying a failed purchase. For price-related failures, run “Check Availability” again before presenting the user with another purchase attempt.

Management interface

The same API that powers search and registration also drives the customer-facing domain dashboard. GET /core/v1/domains provides the domain list used to populate the customer-facing dashboard. The response surfaces the key status fields your dashboard needs, including expiration date, autorenewal state, privacy status, and lock state. Render these in your UI so customers can see domain health at a glance without leaving the platform.

The core management operations cover the full domain lifecycle:

• Update autorenewal, transfer lock, and WHOIS privacy state through the domain update endpoint.
• Set and update registrant contact information. Some TLDs require contact verification after updates, so build an in-product notification path for verification emails.
• The API provides CRUD operations for DNS records and nameservers, allowing you to build DNS management into the same interface.
• WHOIS Privacy is available as a separate purchase, then toggle-able via the API. Some TLDs don't support WHOIS privacy, so check the TLD list for your supported set.
• Surface renewal dates prominently. Users who miss renewals churn for a painful reason, and explicit domain renewal is available through the API in addition to autorenewal settings.

For applications that need push-based status updates rather than polling, webhooks are available as a later enhancement. When implementing them, verify webhook authenticity before processing events.

Edge cases to handle before launch

A search result that looks clean can still produce a failed checkout. The issues usually appear in three areas, premium domains, non-registration purchase types, and TLD-specific requirements. Work through all three before you ship to production.

Start with a curated TLD list. Don't expose every TLD the API supports on day one. Pick a short list of TLDs with predictable registration requirements. .com, .net, .co, and .io are good starting points. Expand from there once you've confirmed the checkout path works end-to-end for each one.

Handle premium: true explicitly. Search results flag premium domains with a premium boolean. These domains require the purchasePrice field in “Create Domain” (sourced from “Check Availability”, not from search), and their prices can change. If you're not ready to build a premium checkout path, filter premium: true results out of your search UI for the MVP and return them as unavailable.

Treat non-registration purchaseType values as unsupported. If “Check Availability” returns a purchaseType other than "registration", such as "aftermarket", don't send that domain through your standard checkout. Surface it as unavailable for your current storefront rather than routing it through a flow you haven't built.

Run checkAvailability immediately before every “Create Domain” call. The window between a search result and a registration attempt is enough for availability or pricing to change. Zone Check results are a fast screening signal rather than an authoritative availability check, so any domain that passes Zone Check still goes through “Check Availability” before purchase.

Claims-period domains and ccTLD requirements need separate handling. Domains subject to a trademark claims period require additional handling before registration proceeds, including presenting the required claims notice to the registrant. Country-code TLDs often require eligibility data (local presence, citizenship) that standard forms don't collect. Both are solvable, but neither fits into an MVP checkout path without additional work. Exclude them from the initial TLD list.

Start building your storefront today

The architecture this guide covers is straightforward. Use domains:search for discovery, domains:checkAvailability to confirm the exact domain and price at checkout, POST /core/v1/domains to complete the registration safely, and the management endpoints to keep the full domain lifecycle inside your platform. Storefronts that need faster discovery at scale can add domains:zoneCheck as a screening layer without changing the purchase flow.

Railway's integration proves the timeline is real. Beacons and Hercules also used our API to bring domain registration into its platform, providing another example of a native domain experience built around the same API. Both started from the same place, a self-serve API account and the Reseller Quickstart guide.

We handle the registrar infrastructure while your platform controls the customer-facing experience. To start building, explore our API documentation at docs.name.com. There are no subscription costs to get started, and you pay for the domains you register. For high-volume integrations with custom pricing and direct team access, reach out to our team.