Customize address validation

You can use the Admin API to specify whether a default address field is required and to create patterns that validate user input for default address fields.

You can customize validations for addresses that are found on profiles, accounts, account registration requests, as well as payment and shipping group pages. Addresses found on credit card, inventory location or the Ship from Warehouse location address in the tax processing setting pages cannot include custom validations.

All the validations described in this section are customized with the Admin API itemtypes endpoint and the customizations made to the address field apply on all sites and for all countries, through both the Commerce UIs and the REST APIs. If you need to configure country-specific validations, you must work with a server-side extension (SSE) and custom widget for customized addresses. See Customize address formats using the API for more information.

Validate address input

You can configure Commerce to perform server-side and client-side validation on any default or custom address field to ensure that the value entered matches a regular expression validation pattern you specify. For example, you could require that first and last names contain only letters and be no longer than 20 characters with the validation pattern ^[A-Za-z]{20}.

Note: For number type custom properties, values sent in the payload will be converted to decimals (double) in the API and then validated. To apply validations for this, the validation pattern should be in the form of ^[0-9]+([.][0-9]+)?$, where the first 0-9 represents the integer part and the second 0-9 represents the decimal part. This pattern should be customized according to the requirements of the particular address field.

When you specify a validation pattern for an address field, Commerce applies the validation to values entered through the storefront or administration interface, REST API calls, CSV imports, and bulk imports. It is important to keep in mind that Commerce does not verify that your validation-pattern string is a valid regular expression. Make sure that your validation patterns are appropriate and not contradictory for the fields to which they apply. Otherwise, shoppers and administrators and administrators might get unexpected results when trying to enter addresses.

Use the Admin API updateItemType/contactInfo endpoint to add a validation pattern to an address field.

For example, the following sample issues a PUT request to /ccadmin/v1/itemTypes/contactInfo to apply a validation pattern to US mobile phone numbers so that they are formatted as 111-222-3333:

PUT /ccadmin/v1/itemTypes/contactInfo  HTTP 1.1
Authorization: Bearer <access_token>

{"specifications":[ 
  { 
    "id" : "phoneNumber", 
    "required" : false, 
    "validationPattern": "^[0-9]{3}([ -][0-9]{3}([ -][0-9]{4})?$", 
    "default": null 
  } 
]}

Note: In this example, no default value is provided. However, if you do provide a default value, make sure it adheres to the validation pattern set for the property. Additionally, if you are working with custom addresses that you created with server side extensions, make sure that validation patterns for fields such as postalCode are broad enough to allow values for all countries your custom addresses support. See Customize address formats using the API for more information.

Make an address field required or optional

Commerce requires that a default address (that is, an address that ships with the product) contain values for a number of address fields, such as City, State, or Country. You can use the Admin API to mark a number of address fields as required or optional, depending on their usage. When you change an address field's required property value, that value applies to the field everywhere it is used.

Note: This section describes only default address properties and not to custom properties you have created. For more information about custom address properties, see Customize address formats using the API.

The following table shows which address fields are required and optional by default for different types of Commerce addresses and tasks.

Property	Account: New Address	Individual Shopper: New Address	Account: Place Order	Individual Shopper: Place Order
firstName	Optional	Optional	Required	Required
lastName	Optional	Optional	Required	Required
companyName	Required	Optional	Optional	Optional
phoneNumber	Optional	Optional	Optional	Optional
address1	Required	Required	Required	Required
city	Required	Required	Required	Required
state	Required	Required	Required	Required
postalcode	Required	Required	Required	Required
country	Required	Required	Required	Required

The firstName, lastName, country, and companyName fields, which are required by default, cannot be made optional. Additionally, you cannot make required fields optional for addresses found on credit card, inventory location or the Ship from Warehouse location address in the tax processing setting pages.

Use the Admin API updateItemType/contactInfo endpoint to make an address field required or optional.

For example, the following sample issues a PUT request to /ccadmin/v1/itemTypes/contactInfo to make the first line of an address field optional:

PUT /ccadmin/v1/itemTypes/contactInfo  HTTP 1.1
Authorization: Bearer <access_token>

{"specifications":[
{
  "id" : "address1",
  "required" : false
}
]}

Keep in mind that the Commerce REST API documentation describes default property values and does not update to match any customizations you make to default address fields. For example, if you make a required address field optional, the REST API documentation will still describe the field as being required.