Custom Domain Fields

Domain registration fails if the domain registry does not receive all of the required information. For example, registration generally fails if you do not include Registrant Legal Type and Registered Entity Name values. Domain fields appear in the shopping cart during the Domains Configuration step of the order process.

To help ensure that customers provide all of the necessary information, you can customize additional domain fields (extended attributes) to display during the ordering process for specific TLDs.

For more information about domains in WHMCS, see Domain Management.

Domain Field Files

You can find the default field definitions that ship with WHMCS in the /resources/domains/dist.additionalfields.php file.

Do not edit this file directly.

To customize the fields, create a new /resources/domains/additionalfields.php file.

Add or Edit Fields

To add a new field, create a new entry in your custom /resources/domains/additionalfields.php file. Use the field formatting in the /resources/domains/dist.additionalfields.php file as a reference:

$additionaldomainfields[""][] = array(
"Name" => "Date of Birth",
"Type" => "text",
"Size" => "30",

To edit an existing field:

  1. Copy and paste the field definition from the /resources/domains/dist.additionalfields.php file into your custom /resources/domains/additionalfields.php file.
  2. Remove any key-value pairs for parameters that you do not want to customize.
  3. Customize the remaining options.

Display Names

To define a Display Name value, add the pipe (|) symbol with the desired display name (for example, 1|Individual):

$additionaldomainfields[""][] = array(
"Name" => "Legal Type",
"Options" => "1|Individual,2|UK Limited Company,3|UK Public Limited Company",

Prepopulated Data Variables

When you set Type to dropdown, you can use the following prepopulated variables:

{Countries}Provides a comma-separated list of countries. The system will save a full country name and pass it to the registrar for the field (for example, United Kingdom).
{CountryCodeMap}Provides an associative key-and-value pair list of country codes and country names. This will display the full country name for a user to choose, but it will only store and pass the ISO country code to the registrar (for example, GB).

For example:

$additionaldomainfields[""][] = array(
"Name" => "Registered Country",
"Type" => "dropdown",
"Options" => "{Countries}",

Conditional Requirements

You can set additional domain fields as never required, always required, or conditionally required. A conditional requirement allows you to denote a field as required only when another field contains a certain value. This allows you to define more complex validation rules.

For example, the following entry defines a conditionally-required additional domain field:

$additionaldomainfields[''][] = [
'Name' => 'Company ID Number',
'LangVar' => 'uktldcompanyid',
'Type' => 'text',
'Size' => '30',
'Required' => [
'Legal Type' => [
'UK Limited Company',
'UK Public Limited Company',

The example above only requires the Company ID Number field when the value of the Legal Type field is either UK Limited Company or UK Public Limited Company.

To define a conditional requirement, set the value of the Requires key to an array containing a list of field names and values that trigger the requirement. The array syntax here supports defining multiple fields. The system will require the field if any of the required fields have one of the defined values.

Remove a Field

To remove an existing field, define the field within your custom /resources/domains/additionalfields.php file and set the Remove attribute to true.

$additionaldomainfields[""][] = array(
"Name" => "Company ID Number",
"Remove" => true,

Translate a Field

You can translate field names using language override files. This allows you to change the label in the shopping cart based on the viewer’s set language.

To translate a field name:

  1. Define the field within your custom /resources/domains/additionalfields.php file and set the LangVar attribute to the desired language variable.
$additionaldomainfields[""][] = array(
"Name" => "Legal Type",
"Options" => "Individual,UK Limited Company,UK Public Limited Company",
"LangVar" => "uktldlegaltype",
  1. Add the translation string with the corresponding attribute to your language override file:
$_LANG['uktldlegaltype'] = "Custom Field Label Text";

For more information about localization in WHMCS, see Localization and Easy Translation.

Last modified: June 5, 2024