WooCommerce Custom Checkout Field — Add and Validate with PHP

The woocommerce_checkout_fields filter is WooCommerce’s single entry point for modifying checkout fields. Before this hook, the only way to add a field was to override the checkout/form-billing.php template — which means copying the entire template into your theme and manually maintaining it through every WooCommerce update. This filter gives you the same $fields array that WooCommerce passes to its own template, so you append a new entry without touching any template file. The array structure — type, label, required, class, priority — mirrors WooCommerce’s own field definitions, meaning your custom field behaves identically to native fields: same CSS classes, same responsive layout, same validation markup.

woocommerce_checkout_process is the validation gate. It fires after the form is posted but before the order post is created, which is exactly when you want to reject invalid input — no order means no cleanup, no orphaned meta, no payment attempt. wc_add_notice( ..., 'error' ) is WooCommerce’s unified notice system; an error-level notice halts checkout and re-renders the form with the notice displayed above the fields. The user’s existing form values are preserved because WooCommerce re-renders the form from $_POST. Compare this to template-override validation in checkout/form-checkout.php — that approach requires manual re-rendering of every field.

woocommerce_checkout_update_order_meta fires immediately after the order object is fully saved. By this point, $order_id is a valid post ID, payment has been processed (or failed), and the order has a status. Because this hook receives only the order ID — not the full WC_Order — you read the submitted value from $_POST directly. This is deliberate: the WC_Order object doesn’t know about your custom field because it’s not a native WooCommerce property. The underscore prefix convention (_delivery_instructions) marks this as “hidden” meta — it won’t appear in the Custom Fields metabox but is still queryable via get_post_meta() and exportable by tools like WooCommerce Customer/Order Export.

Two display hooks cover the two audiences for order data. woocommerce_admin_order_data_after_billing_address targets the store manager — it inserts content into the Edit Order screen right after the billing address box, which is where most site owners look for customer instructions. woocommerce_email_order_meta targets the customer and any CC recipients — it fires at the bottom of every transactional email (order confirmation, invoice, shipping notice) after the order meta table. Both hooks receive the WC_Order object, so you can read any registered post meta, not just the ones you added. This means you could display the field conditionally — only for shipping orders, only for selected payment gateways — by checking $order->get_shipping_method() or $order->get_payment_method().

The production version in Step 5 combines all four concepts into one file with execution-order documentation. Three new production details are worth noting: 1) wc_clean() replaces the raw $_POST access from earlier steps — it’s WooCommerce’s own sanitizer that handles multi-dimensional arrays and slashed data, which matters if your server runs with magic_quotes. 2) The maxlength attribute is set on the textarea — not a security control (users can bypass it), but a UX guard that prevents a customer from accident ally pasting a 5,000-character message. 3) The admin display uses a styled <h4> heading rather than inline bold text — it sits alongside WooCommerce’s native “Billing address” heading and looks intentional, not hacked in.

Create the file. Copy the Step 5 code into inc/woo-checkout-fields.php. In functions.php, add this at the bottom (after your theme setup function):

require_once get_template_directory() . '/inc/woo-checkout-fields.php';

No conditionals like is_plugin_active( 'woocommerce' ) are needed — if WooCommerce isn’t active, these hooks simply never fire. WordPress silently ignores hooks whose tagged callbacks don’t have a matching do_action() call.

Verify the field appears. Go to your checkout page, add an item to the cart, and proceed to checkout. You should see a “Delivery Instructions” textarea below the billing fields. If you don’t, check three things: a) Is the file being loaded? Add error_log( 'woo-checkout-fields loaded' ) at the top of the file and check your debug log. b) Is WooCommerce active? The hooks won’t error without WooCommerce, they just won’t fire. Check that WC() exists before requiring: if ( function_exists( 'WC' ) ) { require_once ... }. c) Is your theme’s checkout template overridden? If themes/your-theme/woocommerce/checkout/form-billing.php exists and was customized, it might not call woocommerce_form_field() for the full $checkout->checkout_fields array — it might hardcode specific fields.

Test the validation. Enter fewer than 10 characters in the Delivery Instructions field and click Place Order. The checkout should reload with a red error notice: “Delivery Instructions must be at least 10 characters.” Enter 10 or more characters (or leave it blank) and the order should complete normally. Critical: test with both filled and empty values. A field that blocks checkouts when blank when it’s supposed to be optional is the most common bug.

Verify data persistence and display. After a successful test order, go to WooCommerce → Orders, find your order, and click to edit. Below the billing address, you should see “Delivery Instructions” followed by your test message. Open the order confirmation email that was sent to the customer — the same message should appear below the order table. If it doesn’t appear in both places, check the hook names for typos (they’re long and easy to get wrong). Tip: use echo '<!-- hook fired -->'; as a temporary debugging line inside each callback to verify the hooks are firing — the comment will be visible in the page source and raw email HTML.

Add multiple fields at once. The checkout fields array is associative — add as many keys as you need in the same filter callback:

add_filter( 'woocommerce_checkout_fields', function( $fields ) {
    $fields['billing']['gift_message'] = [
        'type'  => 'textarea',
        'label' => 'Gift Message',
        'class' => [ 'form-row-wide' ],
    ];
    $fields['billing']['hear_about_us'] = [
        'type'    => 'select',
        'label'   => 'How did you hear about us?',
        'options' => [ '' => 'Select...', 'google' => 'Google', 'friend' => 'A friend' ],
        'class'   => [ 'form-row-wide' ],
    ];
    return $fields;
} );

Then validate and save each field in their respective hooks with the same pattern — wc_add_notice() per failing field, update_post_meta() per saved field.

Use different field types. The type key accepts any WooCommerce-compatible field type: text, textarea, select, checkbox, radio, password, tel, email, number, date. For selects and radios, provide an options array. For checkboxes, note that unchecked boxes send no $_POST value — use $_POST['field_name'] ?? '' to handle the missing key. For a file upload, use type => 'file' but be aware the upload handling is significantly more complex — WooCommerce needs additional hooks for file validation (woocommerce_checkout_process will see $_FILES, not $_POST).

Conditional visibility — show the field only for certain orders. The first hook (woocommerce_checkout_fields) has full access to the checkout session. You can check cart contents and hide the field when irrelevant:

add_filter( 'woocommerce_checkout_fields', function( $fields ) {
    $has_shipping = false;
    foreach ( WC()->cart->get_cart() as $item ) {
        if ( $item['data']->needs_shipping() ) { $has_shipping = true; break; }
    }
    if ( ! $has_shipping ) {
        unset( $fields['billing']['delivery_instructions'] );
    }
    return $fields;
} );

This is safer than adding a <style> block to hide it — removing the field from the array means the HTML never reaches the browser, and no attacker can submit a hidden field value via DevTools.