CheckoutWC checks checkout fields as customers fill them in, and shows a message under any field that needs fixing, so mistakes are caught before the customer clicks to pay. Most stores never need to change this. The code examples on this page are for developers.
When you’d use this
- A customer tells you the checkout rejected a valid email address.
- You want to understand one of CheckoutWC’s error messages.
- You want different wording, or a check of your own, such as requiring a house number in the street address.
Built-in checks and their messages
- Required fields: WooCommerce’s required fields must be filled in.
- Email: the address must be in a valid format, and its domain must be able to receive email: “Email address contains invalid domain name.” See Email domain check.
- Postcode: must be valid for the selected country. The message is “Please enter a valid” followed by the field’s name, for example “Please enter a valid postcode / ZIP.” US ZIP+4 codes are accepted with or without the hyphen.
- Names: the first and last name can’t be an email address: “Please enter a name, not an email address.” With the full name field on, two words are needed: “Please enter your first and last name.”
- Phone: with the international phone field on and the phone required: “Please enter a valid phone number.” See Phone fields.
Email, name, address and postcode fields are checked when the customer leaves the field or changes it. The state and phone fields are also checked as the customer types.
Email domain check
CheckoutWC checks that the email address’s domain has a mail server, which catches typos such as “gmail.con”. Your store’s own server does the lookup when the customer enters their email. Common email providers, such as Gmail, Outlook and iCloud, skip the check because they’re known to be valid.
Very occasionally, a real address is rejected, for example on a new domain or a company mail server with unusual settings. To accept a specific domain without turning the check off, a developer can add this snippet in the PHP Snippets box (CheckoutWC » Advanced, Scripts tab) or a code snippets plugin, listing the domains to allow:
add_filter( 'cfw_email_domain_valid', function ( $valid, $domain ) {
return $valid || in_array( strtolower( $domain ), array( 'example-company.com' ), true );
}, 10, 2 );
To turn the domain check off completely:
add_filter( 'cfw_disable_email_domain_validation', '__return_true' );
Email format is still checked. The Disable Email Domain Autocomplete setting under CheckoutWC » Pages » Checkout » Field Options is separate: it only stops CheckoutWC suggesting common domains as customers type.
Change an error message
CheckoutWC uses the Parsley validation library, so a field’s message can be set with Parsley’s data-parsley-error-message attribute. For example, for the billing first name and email:
add_filter( 'woocommerce_checkout_fields', function ( $fields ) {
$fields['billing']['billing_first_name']['custom_attributes']['data-parsley-error-message'] = 'Please tell us your first name.';
$fields['billing']['billing_email']['custom_attributes']['data-parsley-error-message'] = 'Please check your email address.';
return $fields;
}, 100001 );
Use the same pattern for other fields: the group (billing, shipping or order) and the field’s key, such as shipping_city or order_comments.
Change when a field is checked
Parsley’s data-parsley-trigger attribute sets when a field is checked. For example, to check the email only when the customer leaves the field:
add_filter( 'woocommerce_checkout_fields', function ( $fields ) {
$fields['billing']['billing_email']['custom_attributes']['data-parsley-trigger'] = 'focusout';
return $fields;
}, 2000 );
Translate error messages for another language
CheckoutWC’s field errors come from the Parsley.js library, which has messages for most languages. For a language it doesn’t include, such as Icelandic or Vietnamese, the errors show in English. A developer can add them with the cfw_js_parsley_messages JavaScript filter, available from CheckoutWC 11.5.0.
Add a script like this in the Footer Scripts box (CheckoutWC » Advanced, Scripts tab), with your language’s code and your own wording:
<script>
( function () {
var hooks = window.cfwHooks || ( window.wp && window.wp.hooks );
if ( ! hooks ) {
return;
}
hooks.addFilter( 'cfw_js_parsley_messages', 'my-store', function ( messages, locale ) {
if ( 'is' !== locale ) {
return messages;
}
return Object.assign( {}, messages, {
required: 'Þessi reitur er nauðsynlegur.',
type: { email: 'Netfangið er ekki gilt.' }
} );
} );
} )();
</script>
localeis the first part of your site language, for exampleisfor Icelandic orvifor Vietnamese. The exceptions arept-brandpt-ptfor Portuguese,nofor Norwegian Bokmål and Nynorsk, and your WPML language code on a WPML site.- The keys are Parsley’s message names, such as
required,minlengthandtypewithemailornumber. Any message you leave out stays in English. - The same filter changes messages in a language Parsley already includes.
- The filter runs when the page finishes loading, so add the script in the Footer Scripts box, which runs before that.
Add your own validation rule
Parsley can run your own checks. There are two parts: the validator, and the field it applies to.
Require a house number in the street address
This rule rejects a street address without a number. Add it in the PHP Snippets box or a code snippets plugin:
add_filter( 'woocommerce_default_address_fields', function ( $fields ) {
$fields['address_1']['custom_attributes']['data-parsley-pattern'] = '/^(?=.*\d).+$/';
$fields['address_1']['custom_attributes']['data-parsley-error-message'] = 'Please include your house number in the street address.';
return $fields;
}, 100001 );
If you use Enable Separate House Number and Street Name Address Fields, you don’t need this: the house number has its own required field.
Also require an apartment or unit number
Only use this if you need a unit number on every order, because it blocks customers who live in a house with no unit. This version passes only if the address has a house number and either “Apt” or “Unit” followed by a number, a #, or a second number:
add_filter( 'woocommerce_default_address_fields', function ( $fields ) {
$fields['address_1']['custom_attributes']['data-parsley-pattern'] = '/^(?=.*\b\d+\b.*(?:Apt\s+\d+|Unit\s+\d+|#|\d+-|\b\d+\b)).+$/i';
$fields['address_1']['custom_attributes']['data-parsley-error-message'] = 'Please include your house number and your apartment or unit number in the street address.';
return $fields;
}, 100001 );
For example, “123 Main St Apt 4” and “123 Main St #4” pass, and “123 Main St” doesn’t. Use one of the two snippets, not both.
Write a custom validator
For a check Parsley doesn’t have, register a custom validator in the Footer Scripts box (CheckoutWC » Advanced, Scripts tab). Wrap it so it runs once the page has loaded:
<script>
jQuery( window ).on( 'load', function () {
window.Parsley.addValidator( 'multipleOf', {
requirementType: 'integer',
validateString: function ( value, requirement ) {
return 0 === value % requirement;
},
messages: { en: 'This value should be a multiple of %s.' }
} );
} );
</script>
Then attach it to a field with a snippet like the ones above, for example $fields['billing']['billing_company']['custom_attributes']['data-parsley-multiple-of'] = '3';.
Common issues
“Email address contains invalid domain name.” for a real email address
The domain’s mail server couldn’t be found from your store’s server. If it’s one domain, allow it with the cfw_email_domain_valid snippet in Email domain check.
Every email address is rejected except Gmail, Outlook and similar
Your server’s DNS lookups are failing, so every domain that isn’t on CheckoutWC’s list of common providers fails the check. Ask your web host to check the server’s DNS. Until it’s fixed, turn the domain check off with the cfw_disable_email_domain_validation snippet in Email domain check.
A custom validator never runs
The script may run before CheckoutWC has loaded Parsley. Wrap it in jQuery( window ).on( 'load', … ) as in the example, and check the browser console for errors.
A custom message doesn’t change the postcode, phone or name message
These fields use CheckoutWC’s own checks, which set their messages separately. The data-parsley-error-message attribute may not replace them. Test the field after adding the snippet.