Add custom fields to WooCommerce checkout
Custom checkout fields let a WooCommerce store collect details that the standard billing and shipping forms do not capture, such as delivery instructions, a preferred contact window or a gift message. The dependable approach is to add the inputs with WooCommerce’s checkout field filter, validate them on the server, and save accepted values as order metadata. Cart totals, tax calculation and payment processing then continue through the normal checkout process.
Australian merchants often have local reasons to request extra information. A courier slot may need to account for traffic between Sydney and Melbourne, a gift order may require a message for the recipient, and a trade customer may need a purchase-order reference. Prices can remain in AUD while WooCommerce applies the 10% GST under the store’s Australian tax settings. The built-in address fields should continue to handle Australian states, territories and four-digit postcodes.
The examples below use a small custom plugin rather than a theme file, so the changes survive a theme replacement. They create three order-level fields, store them safely, and display them in the customer view, order email and admin screen. Keep the example keys unique, prefix any functions, and adapt the labels to the products your store sells.
Plan the fields your store needs
First decide whether a value belongs to the order or to an individual product. Delivery instructions and a contact window are order-level details because they apply to the whole basket. A serial number, engraving choice or product-specific engraving text usually needs line-item metadata instead. Mixing these models can make reports, refunds and email templates unreliable.
Choose fields that customers will understand and staff will use. “Delivery instructions”, “preferred contact window” and “gift message” are practical examples for an Australian store. Avoid asking for information already captured by WooCommerce, including email address, phone number, state or GST details. The core checkout should remain the single source for those values.
Plan a unique key for each field and decide whether it is required, optional or conditional. Keep required fields genuinely necessary, because an avoidable field can increase checkout abandonment. The implementation below uses required delivery instructions and contact window, plus an optional gift message, all stored as private order meta.
Add fields to the checkout form
The woocommerce_checkout_fields filter supplies the form controls. Place these fields in the billing group so their values are available during checkout, while WooCommerce continues to render standard address fields. The form-row-wide class gives textarea inputs a full-width row.
add_filter( 'woocommerce_checkout_fields', 'local_store_checkout_fields' );
function local_store_checkout_fields( $fields ) {
$fields['billing']['local_delivery_instructions'] = array(
'type' => 'textarea',
'label' => 'Delivery instructions',
'description' => 'Where should the courier leave the order?',
'required' => true,
'class' => array( 'form-row-wide' ),
'priority' => 25,
);
$fields['billing']['local_contact_window'] = array(
'type' => 'select',
'label' => 'Preferred contact window',
'required' => true,
'class' => array( 'form-row-wide' ),
'options' => array(
'' => 'Choose a time',
'morning' => 'Morning, 9 am to midday',
'afternoon' => 'Afternoon, midday to 5 pm',
'evening' => 'Evening, 5 pm to 8 pm',
),
);
$fields['billing']['local_gift_message'] = array(
'type' => 'textarea',
'label' => 'Gift message',
'description' => 'Optional message printed on the gift card.',
'required' => false,
'class' => array( 'form-row-wide' ),
'priority' => 27,
);
return $fields;
}
WooCommerce applies normal checkout handling to these controls, including labels, required indicators and submitted values. The contact window uses simple keys for storage, while customers see readable Australian-style times. Adjust the available windows to the courier service and the hours the business actually operates.
Add the snippet to a custom plugin and activate it. These examples target the classic checkout supplied by the WooCommerce Checkout shortcode. The Checkout block does not pass values through this same filter. A block-based store should use a block-compatible field extension or WooCommerce’s current additional-fields tools instead of assuming this filter will work.
Validate and sanitise submitted values
Client-side HTML is only a convenience. Every posted value must be checked again before it reaches the order. Use woocommerce_after_checkout_validation to reject malformed values and WooCommerce’s WP_Error object to explain the problem. Sanitising is separate from validation: it makes an acceptable string safe, while validation decides whether it is allowed.
function local_store_submitted_fields() {
$instructions = '';
$window = '';
$gift = '';
if ( isset( $_POST['local_delivery_instructions'] ) && is_string( $_POST['local_delivery_instructions'] ) ) {
$instructions = sanitize_textarea_field( wp_unslash( $_POST['local_delivery_instructions'] ) );
}
if ( isset( $_POST['local_contact_window'] ) && is_string( $_POST['local_contact_window'] ) ) {
$window = sanitize_key( wp_unslash( $_POST['local_contact_window'] ) );
}
if ( isset( $_POST['local_gift_message'] ) && is_string( $_POST['local_gift_message'] ) ) {
$gift = sanitize_textarea_field( wp_unslash( $_POST['local_gift_message'] ) );
}
return array(
'delivery_instructions' => $instructions,
'contact_window' => $window,
'gift_message' => $gift,
);
}
add_action( 'woocommerce_after_checkout_validation', 'local_store_validate_checkout_fields', 20, 2 );
function local_store_validate_checkout_fields( $data, $errors ) {
$values = local_store_submitted_fields();
$allowed_windows = array( 'morning', 'afternoon', 'evening' );
if ( strlen( $values['delivery_instructions'] ) > 500 ) {
$errors->add( 'local_delivery_length', 'Delivery instructions must be 500 characters or fewer.' );
}
if ( $values['contact_window'] && ! in_array( $values['contact_window'], $allowed_windows, true ) ) {
$errors->add( 'local_contact_window', 'Choose a valid contact window.' );
}
if ( strlen( $values['gift_message'] ) > 250 ) {
$errors->add( 'local_gift_length', 'Gift messages must be 250 characters or fewer.' );
}
}
The helper reads only strings and sanitises each value according to its type. Textarea fields retain line breaks, while the select value is reduced to a key. Length checks and a whitelist prevent oversized or unexpected data from being stored. WooCommerce handles the required-field errors for the two required examples.
Never accept arbitrary HTML, and do not place sensitive information such as health or identity documents in a checkout note. For an Australian business, the purpose and handling of customer data should align with the Privacy Act and the Australian Privacy Principles. Store only what fulfilment needs, restrict staff access and avoid echoing values into logs.
Save accepted values to the order
After validation, persist the values on the order. The woocommerce_checkout_create_order action runs after WooCommerce creates the order and before payment is completed. Reading the sanitised helper again keeps the saving step consistent with the validation step and avoids writing raw $_POST data.
add_action( 'woocommerce_checkout_create_order', 'local_store_save_checkout_fields', 20, 2 );
function local_store_save_checkout_fields( $order_id, $data ) {
$order = wc_get_order( $order_id );
if ( ! $order ) {
return;
}
$values = local_store_submitted_fields();
$order->update_meta_data( '_local_delivery_instructions', $values['delivery_instructions'] );
$order->update_meta_data( '_local_contact_window', $values['contact_window'] );
$order->update_meta_data( '_local_gift_message', $values['gift_message'] );
$order->save();
}
Order metadata is preferable to writing directly to wp_posts or running custom SQL. WooCommerce’s order API handles data types and keeps the data associated with the correct order. Prefixing keys with an underscore hides internal metadata from generic custom-field panels, so the display hooks in the next section remain the intended access point.
The $data argument contains WooCommerce’s processed checkout data, but it does not include these custom fields automatically. For conditional fields, validate the condition before saving; otherwise a hidden field can overwrite a previous value. A payment failure may leave the order unpaid, but its metadata remains attached when the customer retries or staff complete it.
Show saved details to customers and staff
Stored values should be visible in the places staff and customers use. On the customer order page, the woocommerce_order_details_after_order_table hook places a compact summary below the normal billing and shipping table. Escape every value at output time even though it was sanitised on input.
function local_store_contact_window_label( $key ) {
$labels = array(
'morning' => 'Morning, 9 am to midday',
'afternoon' => 'Afternoon, midday to 5 pm',
'evening' => 'Evening, 5 pm to 8 pm',
);
return isset( $labels[ $key ] ) ? $labels[ $key ] : $key;
}
add_action( 'woocommerce_order_details_after_order_table', 'local_store_display_order_fields' );
function local_store_display_order_fields( $order ) {
if ( ! $order instanceof WC_Order ) {
return;
}
$instructions = $order->get_meta( '_local_delivery_instructions' );
$window = $order->get_meta( '_local_contact_window' );
$gift = $order->get_meta( '_local_gift_message' );
if ( ! $instructions && ! $window && ! $gift ) {
return;
}
?>
<section class="woocommerce-order-details local-store-order-fields">
<p><strong>Delivery and contact preferences</strong></p>
<dl>
<?php if ( $instructions ) : ?>
<dt>Delivery instructions</dt>
<dd><?php echo nl2br( esc_html( $instructions ) ); ?></dd>
<?php endif; ?>
<?php if ( $window ) : ?>
<dt>Preferred contact window</dt>
<dd><?php echo esc_html( local_store_contact_window_label( $window ) ); ?></dd>
<?php endif; ?>
<?php if ( $gift ) : ?>
<dt>Gift message</dt>
<dd><?php echo nl2br( esc_html( $gift ) ); ?></dd>
<?php endif; ?>
</dl>
</section>
<?php
}
Order emails and the admin order screen need separate hooks because they use different templates. The woocommerce_email_order_meta_fields filter adds rows to WooCommerce’s order-meta table, while woocommerce_admin_order_data_after_billing_address shows values beneath the billing address. Both contexts should read the stored metadata and escape it again before output.
Customer-facing output should be brief and operational. A gift message may contain personal information, so staff should treat it as order data and copy it only to the relevant packing slip. For operational reporting, WooCommerce order metadata can be exported through the REST API or a purpose-built order-reporting extension without changing checkout.
Test the complete checkout flow
Test the full journey rather than only checking that inputs appear. Place a test order in a sandbox gateway, vary the selected contact window, leave the gift message empty and try an overlong value. Confirm that validation messages return to checkout, accepted values appear on the order, emails contain them and the admin screen shows them.
Check the Australian context as well: the order should still show AUD, configured GST, the customer’s state and postcode, and the correct shipping method. Test a Sydney delivery, a Melbourne delivery and a remote Australian destination to ensure the new fields do not change shipping calculations or payment totals.
Run the site’s normal plugin conflict checks around checkout, payment and tax extensions. The WordPress troubleshooting guides can provide a useful baseline for separating a custom-field issue from a broader WordPress or WooCommerce fault. Record the WooCommerce version, active payment gateway and PHP version when documenting a failure.
A completed test leaves three observable results: validated checkout data, private metadata on the correct order, and safely escaped details for customers and staff. Removing the plugin stops collection and display while leaving existing order records and tax history intact, which makes the change straightforward to audit and roll back.