Custom Fields

From WHMCS Documentation

Custom fields allow you to collect additional information from your clients. WHMCS allows you to set up an unlimited number of customer fields that apply to clients, individual products and services, and support departments. You can set them as either admin-only for private use or public.

For example, you might create custom questions like how a client found your site, whether they want to join the mailing list, or their VAT/Tax Number.

Client Custom Fields

Custom fields for clients display in the client's profile for admins, clients, or both and can optionally display on the order form. Set these to Show on Order Form if you want the client to enter them. You can also leave them as only visible in the admin area, for private entries. The client can view and edit the field values from the client area unless you set them to admin only.

To add a custom field to your clients' profiles:

  1. Go to Configuration () > System Settings > Custom Fields or, prior to WHMCS 8.0, Setup > Custom Client Fields.
  2. Locate the desired custom field to edit or create a new custom field under Add New Custom Field.
  3. Enter the requested field information and choose a field type.
  4. Check the appropriate checkboxes to show or hide the field or require a response.
  5. Click Save Changes.

Searching

  • You can search for the values from custom client fields at Clients > View/Search Clients in the Search/Filter tab.
  • To search a Checkbox custom field, enter "on" in the Custom Field Value field. This will display results that include the checked option.

Product Custom Fields

Custom fields for products display as part of the configuration process when clients purchase a product, or you can choose to only display them in the Admin Area for purchased products. This allows you to collect further information that's specific to an individual product.

Some modules require specific fields, which you can find in the documentation for that module.

You can configure custom product fields in the Custom Fields tab at Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services.

Searching

  • You can search for the values from custom product fields at Clients > Products/Services in the Search/Filter tab for the desired product group.
  • To search a Checkbox custom field, enter "on" in the Custom Field Value field. This will display results that include the checked option.

Support Department Custom Fields

Custom fields for support departments display during ticket submission, or you can optionally choose to only display them in the Admin Area. They allow you to ask users for additional information when opening tickets. The system can use this for things like current usernames and passwords.

You can configure custom support department fields in the Custom Fields tab at Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support > Support Departments.

Field Types

When you create a custom field, you can choose from the following field types:

  • Text Box — For a text entry.
  • Link/URL — A URL. The prefix http:// will automatically be prefixed to any value entered.
  • Password — A value to be encrypted, will appear as a password field type in the client area.
  • Drop Down — A drop-down combo box for a selection of preset options.
  • Checkbox — For a yes-or-no answer.
  • Text Area — For a long text entry of multiple lines.

Validation

The regular expression validation rules allow you to define what value the field can accept. The system won't allow the user to proceed until it passes the validation rule. For example:

A domain name in the format "google.com":

/^([a-zA-Z0-9_-])+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,6})$/

A username between 4 and 28 characters in length, allowing only alphanumeric characters and underscores:

/^[a-z\d_]{4,28}$/i

A telephone number in the following format: (###) ###-####

/^(\(?[0-9]{3,3}\)?|[0-9]{3,3}[-. ]?)[ ][0-9]{3,3}[-. ]?[0-9]{4,4}$/

A date in the format DD/MM/YYYY:

/^\d{1,2}\/\d{1,2}\/\d{4}$/

Numbers only (0-9, any length):

/^[0-9]+$/

See http://www.rexegg.com/regex-quickstart.html for a detailed guide.

You must properly escape any forward slashes in your regular expression using back slashes: \/

Other Settings

Depending on the type of custom field you are creating, you can enable the following options:

Admin Only

Check Admin Only if you want to hide this in the Client Area.

Required Field

Check Required Field if you want to require a response.

Show on Order Form

Check Show on Order Form if you want to display this field on the order form in the Client Area when a client is registering.

Show on Invoice

Check Show on Invoice if you want this field to display on the client's invoices.

You might want to display custom fields on invoices if, for example, you have a client custom field for a Tax ID or VAT Number.

  • Client custom fields will display under the name and address information on the invoice.
  • Product custom fields display as part of the line item descriptions for those products.

If you enable Store Client Data Snapshot in the Invoices tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings. Then, create or edit a custom field after invoice creation, the invoice won't reflect those changed values and new fields. However, future invoices will show them.

Displaying Custom Fields in Emails

You can add custom fields to email templates using merge fields. For more information, see Email Templates.

Displaying Custom Fields on Pages

To display custom fields on service-related pages, the merge fields take the following format, where fieldname is the name of the custom field, lowercase with no spaces:

{$client_custom_field_fieldnamehere}

For example, for IP address, the merge field would be:

{$service_custom_field_ipaddress}

For fields with Friendly Names, use the friendly name, rather than the machine name, to reference the field. For example, if the field name is:

CustomerType

Reference it as:

{$client_custom_field_customertype}

However, if the field name is using a friendly name, like this:

CustomerType|Type of Customer

Reference it as:

{$client_custom_field_typeofcustomer}

Multi-line Text Areas

For text area custom fields, you can enter data on multiple lines. By default, the system displays it in merge fields on a single line. To see the custom field data as it was entered in the field, use the following merge field:

{$client_custom_field_fieldnamehere|nl2br}

or

{$service_custom_field_ipallocation|nl2br}

Friendly Display Names

Sometimes, a module may require that you format a custom field value in a certain way, which may be hard for visitors to understand. WHMCS can display a friendly name to visitors on the order form, emails, and invoices, and still send the required machine code to the module.

Custom Field Friendly Names

To achieve this, use the format "required value|display value". For example:

  • Disk Space|Your Web Quota
  • 10000MB|10 Gigabytes
  • rbx01ssd|French Server - Solid State Drive