Skip to content
agovena.
agovena.
Get started
Community

Provider guides

Namecheap Domains: configuration and operations

Check availability, register and renew domains through the Namecheap XML API and manage host records on Namecheap BasicDNS.

On this page

Status and workflow

The Namecheap Domains extension connects the Domains Module to Namecheap in two roles. namecheap-registrar handles availability, registration, renewal and status refresh through the Namecheap XML API. namecheap-dns manages host records on Namecheap BasicDNS for domains in the same Namecheap account. Every command is a form-encoded HTTP POST to the sandbox or live endpoint.

Production-ready for the documented scope. Every operation under Supported operations is implemented against the Namecheap XML API commands and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Namecheap account remains an operator responsibility: run one registration, renewal and DNS change in the Namecheap sandbox and then on your live account from the allowlisted IPv4 address. Operations under Not supported are not advertised.

Requirements

  • Agovena Core ^0.0.1.
  • The Domains Module, enabled before this extension.
  • A Namecheap account with API access and the public IPv4 address of your Agovena server on the API allowlist. Namecheap accepts IPv4 only.
  • Sandbox and live use separate accounts, API keys and allowlists.
  • A cache store with atomic locks, such as Redis, database, file, Memcached or DynamoDB, for DNS changes.

Set up the package

  1. Enable the Domains Module, then open Admin > Extensions and enable Namecheap Domains.
  2. Enable API access in the Namecheap dashboard and add the public IPv4 address of the server to the allowlist.
  3. Save api_user, api_key, username and client_ip. The API key is stored as a secret and only sent in the POST body, never in a URL, log or exception.
  4. Keep sandbox enabled (https://api.sandbox.namecheap.com/xml.response) until a sandbox registration, renewal and DNS change succeed.
  5. Switch sandbox off to use https://api.namecheap.com/xml.response with live credentials and the live allowlist.
  6. Registration uses the configured term in years, from 1 to 10.

Supported operations

  • Availability with namecheap.domains.check. IDN names (xn--) and TLDs that need extended attributes (.us, .eu, .ca, .co.uk, .org.uk, .me.uk, .nu, .com.au, .net.au, .org.au, .es, .nom.es, .com.es, .org.es, .de, .fr) are reported unavailable without calling Namecheap. Premium names and names with an Early Access fee are unavailable. The price is the one-year REGISTER price of your account from namecheap.users.getPricing, cached for one hour. Without a usable price the domain stays available without a price.
  • Registration with namecheap.domains.create. The contact comes from the default billing address of the customer, or the oldest address, and is used for all four roles. It needs a first and last name, address line, city, region, postal code, ISO 3166-1 alpha-2 country, email address and a phone number written as +<country code> <number>. Missing fields are refused before any call. Domain privacy is not requested and no custom nameservers are sent, so new domains use BasicDNS.
  • Status refresh for registrations in registering. The scheduled agovena:refresh-domain-registrations command only reads namecheap.domains.getInfo.
  • Renewal with namecheap.domains.renew for non-premium domains owned by the API user that have a recorded expiry date.
  • DNS zone check with namecheap.domains.dns.getList. It is read-only and requires the domain to use BasicDNS.
  • DNS records for A, AAAA, CNAME, MX and TXT. A needs IPv4, AAAA needs IPv6, MX needs a priority from 0 to 65535 and the TTL must be between 60 and 60000 seconds. Names may be @, relative or complete names inside the domain.

Not supported

  • TLDs that need extended attributes, IDN registrations, premium and Early Access registrations, and premium renewals.
  • Transfers, reactivation, contact updates, domain privacy, registrar lock, auth codes and nameserver changes, including domains.dns.setDefault and domains.dns.setCustom.
  • Editing URL, URL301, FRAME, CAA, ALIAS, NS and MXE hosts. They are preserved and can be deleted.
  • Email forwarding, dynamic DNS, child nameservers and a health check callback.

Failure handling and ownership

  • Namecheap reports errors inside an HTTP 200 body. Only Status="OK" with a response for the requested command is accepted. Status="ERROR" keeps only the documented error number, because the provider text can echo request values.
  • Non-2xx answers, redirects, empty or non-XML bodies and unknown shapes fail. XML with a DOCTYPE is refused before parsing and external entities are never loaded.
  • For domains.create and domains.renew, every answer that is not definitive, including a timeout, is reported as an unknown outcome that needs reconciliation. A retry is safe because both workflows start with read-only checks.
  • Before registering, domains.getInfo reports a domain that is already in your account as active instead of registering it again. A domain in the account that the API user does not own is refused.
  • Before renewing, the provider expiry is compared with the recorded expiry. If an earlier renewal already went through, it is reported as active and nothing is charged. Any other mismatch is refused for manual reconciliation.
  • DNS changes are read-modify-write: getHosts, one change, then setHosts with the complete list under a per-domain lock. All other hosts, MX priorities and TTLs are written back exactly as read. Record IDs are fingerprints, so a record that changed since it was listed is refused.
  • Custom MX hosts use EmailType=MX. When the domain uses a Namecheap mail setting such as forwarding or Private Email, adding or keeping MX hosts is refused instead of switching that setup.
  • All HTTP calls are refused in the demo environment.

Configuration contract

Field Type Required Secret Default
api_user string No No Empty
api_key string No Yes Empty
username string No No Empty
client_ip string No No Empty
sandbox boolean No No true

All fields are optional in the manifest, but every API call needs api_user, api_key, username and an allowlisted IPv4 client_ip. Other client_ip values are refused before any request. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation