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
- Enable the Domains Module, then open Admin > Extensions and enable Namecheap Domains.
- Enable API access in the Namecheap dashboard and add the public IPv4 address of the server to the allowlist.
- Save
api_user,api_key,usernameandclient_ip. The API key is stored as a secret and only sent in the POST body, never in a URL, log or exception. - Keep
sandboxenabled (https://api.sandbox.namecheap.com/xml.response) until a sandbox registration, renewal and DNS change succeed. - Switch
sandboxoff to usehttps://api.namecheap.com/xml.responsewith live credentials and the live allowlist. - 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-yearREGISTERprice of your account fromnamecheap.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 scheduledagovena:refresh-domain-registrationscommand only readsnamecheap.domains.getInfo. - Renewal with
namecheap.domains.renewfor 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.setDefaultanddomains.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
DOCTYPEis refused before parsing and external entities are never loaded. - For
domains.createanddomains.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.getInforeports a domain that is already in your account asactiveinstead 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
activeand nothing is charged. Any other mismatch is refused for manual reconciliation. - DNS changes are read-modify-write:
getHosts, one change, thensetHostswith 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
demoenvironment.
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.