Customising Countries and Calling Codes

From WHMCS Documentation

This page describes a feature available in version 7.0 and above.

What is the Countries File?

The countries.json files determines the countries that appear within WHMCS and their respective calling codes.

Primarily, WHMCS uses these lists of country data to determine the contents of the country menu choices for addresses and county call codes. They only have a limited affect on automatic phone number formatting.

Customising Countries

The default country definitions that ship with WHMCS are in resources/country/dist.countries.json. Do not edit this file.

WHMCS 6.9 and earlier
Prior to WHMCS 7.0, this file was located at /includes/countries.php in a different format.

To customise the list of countries, begin by creating a custom countries.json file in the /resources/country/ directory.

ISO-3116 Countries

If you add non-ISO-3166 countries, WHMCS adds them to:

  • The country menu selections for addresses.
  • The country codes used for backend phone parsing.
  • The repository that automatic phone number formatting uses to format phone numbers.

Removing or changing a country or calling code will not alter the default ISO-3166 repository that WHMCS uses for automatic phone number formatting. Changes and removals are limited to the address country menu choices and the backend phone number formatting logic that WHMCS transmits to external service providers like registrars or gateways.

Adding a Country

Inside your custom /resources/country/countries.json file, add a section that resembles this example:

{
    "ABC": {
        "name": "Awesome Best Country",
        "callingCode": 12345
    }
}

This will add a country with the display name Awesome Best Country.

Modifying a Country

Inside your custom /resources/country/countries.json file, add a section that resembles this example:

{
    "GB": {
        "name": "Great Britain",
        "callingCode": 44
    }
}

The above example would customise the display name for United Kingdom (GB) to Great Britain.

Removing a Country

Inside your custom /resources/country/countries.json file, add a section that resembles this example:

{
    "GB": false
}

The above example would remove GB (United Kingdom) from the available countries within WHMCS.

Troubleshooting

If, after making an edit to your custom /resources/country/countries.json file, it does not take effect, this indicates that the file contains invalid syntax. The file must contain valid JSON syntax. Running the contents of your file through an online syntax validation checker can help you find any issues.