Ultimate Guide to WooCommerce Checkout Fields

Posted on June 21, 2018

This post is meant as a one stop shop if you’d like to make any kind of customizations to your WooCommerce checkout fields. Whether this is adding additional fields, removing some unneeded ones or changing the order they’re displayed in.

Additionally there will be guides on how do display fields two field side by side, updates the order totals when a field changes and how to add basic field validation.

Good to Know

These are some good to know files, hooks and functions/methods. Some of these will be used throughout the post, others are related and may be of use for your specific use case.

Files/Functions

includes/class-wc-countries.php﻿​

get_default_address_fields()

get_address_fields( $country = '', $type = 'billing_' )

includes/class-wc-checkout.php

get_checkout_fields( $fieldset = '' )

includes/wc-template-functions.php

woocommerce_form_field( $key, $args, $value = null )

Hooks

There are different ways (filters) you can modify checkout fields in WooCommerce. The following hooks can be used accordingly to their use case.

woocommerce_default_address_fields﻿ can be used when you’d like to add a address field for all countries.

The woocommerce_billing_fields/woocommerce_shipping_fields hooks﻿ are also address only fields, so be aware that these omit the ‘Company’ field for example and is also not the best place to add product fields for example.

woocommerce_checkout_fields is the last in line, this is the very last filter that can be called and contains all the actual checkout fields that will be displayed to the customer.

Checkout Field IDs

When managing the checkout fields you’ll require the checkout field IDs accordingly. Here’s a full list of all the field IDs accordingly.

Billing Fields

billing_first_name

billing_last_name

billing_company

billing_country

billing_address_1

billing_address_2

billing_city

billing_state

billing_postcode

billing_phone

billing_email

Shipping Fields

shipping_first_name

shipping_last_name

shipping_company

shipping_country

shipping_address_1

shipping_address_2

shipping_city

shipping_state

shipping_postcode

Account Fields

account_username

account_password

Order Fields

order_comments

Adding Checkout Fields

The following example shows the addition of a basic billing field – using the woocommerce_billing_fields﻿ hook.

This example adds a very simple text field to the billing fields. There are many additional options you can pass within the array to customize your checkout field. Below is the entire list of the default attributes (and values) that you can pass and override accordingly.

One important thing to note is that the field ID should be prefixed with billing_, shipping_, account_ or order_ according to where you’re adding the field to. This ensures the field is automatically processed correctly within WooCommerce Core without additional effort needed.

That’s are quite a few arguments! but luckily you don’t need to touch most of them as shown with the basic example. Some of the arguments deserve some additional attention;

Type

The type field is the one that determines what type of field is used. WooCommerce by default has 18 registered field types. Later in this post more about the different checkout field types.

Description

The description argument adds a description to the front-end and will only be visible when the customer is focussed on the specific field.

‘Description’ argument example

Priority

The priority argument is what determines the order in which the checkout fields will appear. All fields are sorted automatically going from low to high, making it easy to determine the position of a field instead of having to have it at a specific index/position within a list/array.

Validate

The validate argument is meant to allow for adding additional validity check(s) to the field. Validation checks are done at the checkout when trying to create the order – so only after the customer presses the “Place order” button.

Checkout Field Types

There are 18 different field types you can choose from by default. I’ll list them all below, some are for more generic use and others are more for one time use such as ‘Country’ or ‘State’, but if wanted you can use them multiple times.

country

state

textarea

checkbox

text

password

datetime

datetime-local

date

month

time

week

number

email

url

tel

select

radio

Creating a Custom Checkout Field Type

Is the field you’re looking for not available in the default list? It is possible to create your own custom field type and use it accordingly. Here’s a quick example of creating a ‘description’ field type that simply adds a description text as a field to the checkout page.

Since ‘description’ is quite general I’ve prefixed it with js_ to ensure the chances of it conflicting is close to zero. With this code in place you can now add your custom field using the js_description in the type parameter. It shows the label argument as the description. Of course you can modify this to output any custom HTML field you want/need.

Take a look at the woocommerce_form_field() function to see how the default fields are formatted and structured. This shows a lot of what is expected and how you can create your own custom field type.

Update Totals on Field Change

By default WooCommerce will update the order totals table automatically when the required address fields are all filled out and when any of those fields change. Updating the order totals table when your custom field changes is very easy..

When adding your custom field, simply add a update_totals_on_change to the class attribute and it will automagically update the totals whenever the field value changes.

Adding Checkout Fields in the Admin

The admin interface does not show the newly added field automatically. There are additional filters where your custom field(s) need to be added to. The following are available for the shipping/billing fields;

woocommerce_admin_billing_fields﻿

woocommerce_admin_shipping_fields

Adding your custom field here is easier then adding it to the checkout, you only have to pass the field ID and the label – most of the time. The following adds the newly added checkout field to the admin.

Take note that the FIELD_IDmust be without the billing_ / shipping_ prefix as WooCommerce adds this automatically.

There are additional attributes you can pass to the array. You can already see I passed show => true in the example. Passing that attribute => value ensures the field and value are shown similar to the Email/Phone fields on the order view.

‘show’ => true

Editing billing fields

The types of editing fields are a bit more limited then the checkout fields, you can only choose to make it a text field (default) or set the 'type' => 'select' to make the edit field a dropdown.

Removing Checkout Fields

Removing any checkout field is quite easy. The only thing to keep in mind is that the ‘Country’ field is a non-removable field as WooCommerce Core does a hard check to see if its available. If you do remove it the order cannot be completed and will give an error saying “Please enter an address to continue.”.

Now – I can’t think of any reason why any store would need this, but the following code removes ALL checkout fields that can be removed, and Woo will still work as expected. You can however easily use this snippet and simply eliminate the code that you don’t want.

Sorting Checkout Fields

Positioning checkout fields is luckily very easy – mostly. WooCommerce Core does all the heavy lifting in term of actually sorting them, you just provide have to provide the correct priority to the field(s).

Checkout Field Default PrioritiesIn order to be able to position your field at the right location you of course need the priority of existing fields. This is the full list of all default fields with their priorities;

First name – 10

Last name – 20

Company name – 30

Country – 40

Street address – 50

Apartment, suite, unit etc. (optional) – 60

Town / City – 70

State – 80

Postcode / ZIP – 90

Phone – 100

Email – 110

Note: For many countries the priority for the Postcode / ZIP field is changed to 65 by WooCommerce.

Repositioning Existing Checkout Fields

You’ve already seen how to provide the priority attribute when adding a new checkout field, to re-position a existing field you can do something like below to accomplish that.

Aligning checkout fields

By default the first- and last name fields are the only two fields that are aligned side by side and the rest of the fields are full width. Aligning the checkout fields can be done by adding one of the below strings to the class attribute when adding a field.

form-row-first﻿

form-row-last

form-row-wide

The first and last name fields have the form-row-first and form-row-last values accordingly to show them side by side. This is an example that gives the same treatment to the two address fields to show them side by side.

Custom Checkout Field Validation

I’ve touched on checkout field validation shortly before showing the WooCommerce Core validation options. Now I’d like to show a custom validation rule. In my example below I added a validation that checks for a valid 10-alphanumeric customer club number.

15 thoughts on “Ultimate Guide to WooCommerce Checkout Fields”

MatthieuAugust 26, 2018 at 6:07 pm

Hello Jeroen,

Many thanks for this great guide. Is there any way to mark the newly added field red when the input is invalid? So the customer immediately notices which field needs to be adjusted. Many thank in advance!

Something like that is possible – I’d recommend adding a specific class to the new field and create a custom JavaScript function that does the validation accordingly. WooCommerce does not have a out-of-the-box solution for that though.

Hi Jeroen,
Thank you it is a great tutorial.
I am trying to use your custom validation function on a not required field. So the field is optional but if the user enter something I validate that. Basically it works well the error message appears above the checkout fields, but the input field remains valid (green). It is possible to force woocommerce to show the related field invalid if the field is optional?

I’ve done a bit of research and it is possible, but does require some additional customization and Javascript coding to accomplish something like that.
If wanted I’d be happy to discuss picking this customization up > feel free to reach out through the contact form to chat about it 😉

Hi Jeroen great article, Im just wondering how to change the “name” attribute from the custom field. I see for example that woocommerce billing phone field has name=”billing_phone” and id=”reg_billing_phone”.

With this function it adds the same name for both attributes. Is this important? Im adding this field to the registration form and I want to use the same field woocommerce has.

I created a custom field (select field) that appears on the Woocommerce checkout page and is named ‘client-type’. If I choose from the available values ‘personal’ or ‘company’ I want the available payment gateways to be changed (enabled/disabled).

The field already contains the classes ‘address-field’ and ‘update_totals_on_change’ and if I select an item (change the content), the order summary box is reloaded.

But now I’m lost… where do I get the selected value of my custom field to filter my gateways? I was hoping something similar like ‘WC()->customer->get_shipping_country()’ is working, but apparently I’m missing something…

How would I reformat the billing phone number field to strip out any parentheses if someone tries to use in the phone number? I ‘m having issues with my shipping plugin if the phone has parentheses in them. Thanks!

Who’s this guy?

My name is Jeroen, go ahead and try to pronounce that! I bet you get it wrong if you’re not Dutch

I am a professional WordPress Plugin Developer, working from Alphen aan den Rijn in the Netherlands. Besides being a seasoned developer, I have a solid background in SEO and have been responsible for hundreds of websites and webshops in my previous work experience.

I build custom plugins for WordPress, WooCommerce and Easy Digital Downloads. My focus is to build the best, secure, reliable, optimized plugins with a good User Experience.

When not working, I like to watch tv series and eat some healthy home-made pizza.