The correct way to add a custom field depends on which WooCommerce checkout your store uses. A classic shortcode checkout uses PHP hooks to render, validate, save, and display order metadata. The Checkout Block uses WooCommerce’s additional checkout-field API and its CheckoutFields helper service. Identify the checkout first; code written for one path will not automatically work in the other.
For a shortcode checkout, the usual flow is woocommerce_after_order_notes (or woocommerce_checkout_fields) for the form, woocommerce_checkout_process for validation, and either woocommerce_checkout_create_order or woocommerce_checkout_update_order_meta for persistence. For a Checkout Block, register the field after woocommerce_init with woocommerce_register_additional_checkout_field(). In both paths, sanitize and validate input before saving, then escape it when displaying it.
As an Amazon Associate I earn from qualifying purchases.
First identify your checkout type
WooCommerce stores can present checkout through the legacy shortcode template or through the newer Checkout Block. Open the page assigned to WooCommerce checkout and edit it in WordPress. A page containing a Checkout block is using the Blocks path; a page whose content is the [woocommerce_checkout] shortcode is using the classic path. Theme customizations and page-builder templates can complicate this, so confirm the actual checkout rendered on the front end before choosing an implementation.
| Decision point | Classic shortcode checkout | Checkout Block |
|---|---|---|
| Registration mechanism | PHP actions and filters such as woocommerce_after_order_notes and woocommerce_checkout_fields |
Additional checkout-field API, registered with woocommerce_register_additional_checkout_field() |
| Minimum version stated in the developer guide | Not stated | WooCommerce 8.9.0 or newer |
| Typical persistence | Order metadata written through a WC_Order object |
WooCommerce manages field storage; address fields are saved to the customer and order, while order-information fields are order-specific |
| Preferred retrieval | $order->get_meta() and other WC_Order methods |
CheckoutFields service methods such as get_field_from_object() and get_all_fields_from_object() |
| Common display target | Custom PHP output in the admin order screen, with additional hooks for other surfaces | Field data can be consumed through WooCommerce’s field services; an editor extension can expose it in order details, emails, and the thank-you page |
Do not register the same field through both systems. That can create duplicate inputs, conflicting values, or a field that appears in one checkout but is never submitted by the other.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Adding a field to the classic shortcode checkout
1. Render the field
The official pattern adds a field after the order notes area with woocommerce_after_order_notes. Use woocommerce_form_field() so WooCommerce supplies consistent markup, labels, classes, and error styling.
<?php
add_action( 'woocommerce_after_order_notes', function ( $checkout ) {
woocommerce_form_field(
'delivery_reference',
array(
'type' => 'text',
'class' => array( 'form-row-wide' ),
'label' => __( 'Delivery reference', 'your-textdomain' ),
'placeholder' => __( 'Optional reference', 'your-textdomain' ),
),
$checkout->get_value( 'delivery_reference' )
);
} );The field key, delivery_reference in this example, must remain consistent in the input, validation code, save callback, and display code. Use a namespaced key in a larger plugin to reduce collisions with another extension.
2. Add or modify fields through the checkout-fields array
If you need to place a field inside a standard billing, shipping, or account section, filter woocommerce_checkout_fields instead of printing a separate field. This is also the route for changing labels, priorities, required flags, or input types of existing shortcode fields.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →<?php
add_filter( 'woocommerce_checkout_fields', function ( $fields ) {
$fields['billing']['delivery_reference'] = array(
'type' => 'text',
'label' => __( 'Delivery reference', 'your-textdomain' ),
'required' => false,
'priority' => 120,
'class' => array( 'form-row-wide' ),
);
return $fields;
} );Do not use both rendering approaches for one key. If you add a field with woocommerce_after_order_notes and also insert that key into the fields array, customers may see two controls and submit an ambiguous value.
3. Validate submitted data
Validation runs during woocommerce_checkout_process. Add a WooCommerce error notice when a value is missing or malformed. Validation should express business rules, not merely repeat sanitization. For example, a reference may be optional but, when supplied, limited to a particular format.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
<?php
add_action( 'woocommerce_checkout_process', function () {
$value = isset( $_POST['delivery_reference'] )
? sanitize_text_field( wp_unslash( $_POST['delivery_reference'] ) )
: '';
if ( $value !== '' && strlen( $value ) > 40 ) {
wc_add_notice(
__( 'The delivery reference must be 40 characters or fewer.', 'your-textdomain' ),
'error'
);
}
} );Use the appropriate validator for the data type: email addresses need an email validator, dates need a date rule, and enumerated values should be checked against an allow-list. Never trust a browser-side required attribute as the only check; requests can be submitted without the browser interface.
4. Save the value as order metadata
Use woocommerce_checkout_create_order when you want to alter the order object while WooCommerce is creating it. The callback receives a WC_Order object, so write metadata with update_meta_data(). The code below sanitizes again at the save boundary, which protects the order even if another caller bypasses the normal form.
Free tools Windows power users keep installed
One-click scans. No signup required.
<?php
add_action( 'woocommerce_checkout_create_order', function ( $order, $data ) {
if ( ! isset( $_POST['delivery_reference'] ) ) {
return;
}
$value = sanitize_text_field( wp_unslash( $_POST['delivery_reference'] ) );
if ( $value !== '' ) {
$order->update_meta_data( 'delivery_reference', $value );
}
}, 10, 2 );WooCommerce’s code reference also documents woocommerce_checkout_update_order_meta, which runs after the order has been created and has an order ID. Use it when metadata must be added after creation. Retrieve the order with wc_get_order(), update it, and persist it.
<?php
add_action( 'woocommerce_checkout_update_order_meta', function ( $order_id ) {
$order = wc_get_order( $order_id );
if ( ! $order || ! isset( $_POST['delivery_reference'] ) ) {
return;
}
$value = sanitize_text_field( wp_unslash( $_POST['delivery_reference'] ) );
if ( $value !== '' ) {
$order->update_meta_data( 'delivery_reference', $value );
$order->save();
}
} );Choose one save hook for a given value. The pre-save hook is appropriate when the order object is being assembled; the post-creation hook is appropriate when you specifically need the existing order ID. Registering both for the same key is unnecessary and can make debugging difficult.
5. Display the value in the admin order editor
The woocommerce_admin_order_data_after_billing_address action places custom output in the admin order screen. Read through the order object and escape the value as HTML text. Do not echo raw metadata, because order fields can contain input supplied by a customer or an integration.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
<?php
add_action( 'woocommerce_admin_order_data_after_billing_address', function ( $order ) {
$value = $order->get_meta( 'delivery_reference', true );
if ( $value === '' ) {
return;
}
echo '<p><strong>'
. esc_html__( 'Delivery reference', 'your-textdomain' )
. ':</strong> '
. esc_html( $value )
. '</p>';
} );The same metadata can be read by your own email, packing-slip, or integration code, but each output surface needs its own suitable hook and escaping context. Escape text with esc_html(); do not use an HTML-safe escaping function for a value that is being inserted into an attribute or URL.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Adding a field to the Checkout Block
Requirements and registration timing
The documented additional checkout-field API requires WooCommerce 8.9.0 or newer. Register fields after the woocommerce_init action, when WooCommerce has loaded the API. A registration made only through shortcode hooks will not add a control to a Checkout Block.
Each field has a location: contact, address, or order. Choose the location according to who the information describes and how it should be retained. WooCommerce documents address fields as being saved to both the customer and the order. Order-information fields are tied to the order rather than being a reusable customer address value.
<?php
add_action( 'woocommerce_init', function () {
woocommerce_register_additional_checkout_field(
array(
'id' => 'your-plugin/business-email',
'label' => __( 'Business email', 'your-textdomain' ),
'location' => 'contact',
'type' => 'email',
'required' => false,
'sanitize_callback' => 'sanitize_email',
'validate_callback' => function ( $value ) {
if ( $value !== '' && ! is_email( $value ) ) {
return new WP_Error(
'invalid_business_email',
__( 'Enter a valid business email address.', 'your-textdomain' )
);
}
},
)
);
} );The example uses sanitize_email and is_email, matching the API’s documented pattern. Adapt the sanitizer and validator to the field type. A phone number, tax identifier, or postal code should not be treated as an email merely because the input element accepts text.
Retrieve Block field values through WooCommerce’s helpers
For Block fields, prefer the WooCommerce CheckoutFields service. Its get_field_from_object() method retrieves one registered field from an order or customer object, while get_all_fields_from_object() returns the registered fields available on that object. These helpers are the forward-compatible integration point because WooCommerce can change internal storage or migrate field data without requiring every extension to know the underlying meta key.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Use the registered field ID, such as your-plugin/business-email, rather than assuming a database key. In a plugin, obtain the service from WooCommerce’s container and pass the order or customer object to the relevant helper, following the method signature for the installed WooCommerce version. Escape the returned value at the point where you render it.
Direct metadata access is available as an integration fallback. WooCommerce documents prefixes for the underlying groups: _wc_billing/ for billing fields, _wc_shipping/ for shipping fields, and _wc_other/ for other checkout data. Treat those prefixes as implementation details. Code that hard-codes them is more likely to need changes if WooCommerce migrates storage.
Sanitization, validation, and output safety
- Sanitize before persistence. Use a sanitizer suitable for the field, such as
sanitize_text_field()for a plain short string orsanitize_email()for an email address. Callwp_unslash()on values read from$_POST. - Validate the business rule. Reject invalid formats, disallowed choices, excessive length, and values that are required only under a particular condition. In the classic checkout, report failures with
wc_add_notice(). In the Blocks API, provide avalidate_callback. - Escape on output. Use
esc_html()for text in an admin paragraph, and the context-specific escaping function when inserting a value into an attribute, URL, or JavaScript string. - Keep the key stable. Renaming a field ID or meta key after orders exist makes historical values appear to disappear unless you provide a migration or read both keys.
- Do not rely on visual controls. A disabled browser field, a client-side required flag, or a hidden input is not a security boundary. Server-side callbacks must perform the final checks.
Displaying fields beyond the admin screen
A custom PHP field is not automatically printed in every WooCommerce surface. The admin order editor example above handles that screen only. If customers or staff need the value in emails, the thank-you page, invoices, packing documents, or a third-party integration, implement the corresponding output or use an extension that supports those destinations.
WooCommerce’s Custom Checkout Fields Editor documentation describes settings that can expose custom fields in order details, customer emails, administrator emails, and the thank-you page. Its Checkout Block positions include locations before or after billing and shipping details. The extension documentation also notes limitations affecting required flags, styling, exact field positioning, and some default values. Treat those behaviors as extension-specific: check compatibility with the installed extension and WooCommerce versions before relying on them in a production workflow.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →An editor extension is usually preferable when non-developers need to add, reorder, or label fields from the WordPress admin. Custom PHP remains the better fit when the value controls pricing or fulfillment logic, requires conditional validation, or must be integrated with a system that expects a precise field ID.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Troubleshooting common failures
The field appears in shortcode checkout but not in the Block
This is expected when the field was registered only with classic hooks. Confirm that the page uses a Checkout Block, verify WooCommerce is at least 8.9.0 for the documented API, and register the field inside a callback on woocommerce_init. Also check that the registration code runs on the front end and that the field’s location is one of the supported values.
The field appears but the order value is empty
Check that the submitted key exactly matches the key read by the save callback. For a shortcode field, inspect whether the input name is the same as the key passed to woocommerce_form_field(). Confirm that your sanitizer is not converting the value to an empty string and that validation is not preventing order creation. For a Block field, retrieve it by its registered field ID through CheckoutFields helpers rather than guessing a meta key.
The value is saved but missing from the admin order screen
Saving and displaying are separate operations. Confirm that the display callback is attached to woocommerce_admin_order_data_after_billing_address, that it reads the same metadata key used during saving, and that the callback receives a valid WC_Order object. An empty-value check may intentionally hide orders created before the field was introduced.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThe field is shown twice
Search for duplicate registrations in both the theme and plugins. A common cause is adding the key to woocommerce_checkout_fields and also rendering it with woocommerce_after_order_notes. Another is registering a classic field and a Block field for a checkout that can switch templates. Keep one implementation for the active checkout.
Direct meta access stops working after an update
Replace hard-coded Block metadata reads with the CheckoutFields service. Direct keys using _wc_billing/, _wc_shipping/, or _wc_other/ are documented as a fallback for integrations, not the preferred long-term API.
A practical implementation and testing checklist
- Identify whether the live page uses the shortcode or Checkout Block.
- Define the field’s purpose, location, key, data type, maximum length, and whether it belongs to the order, customer, or both.
- Implement rendering or registration using only the mechanism for that checkout.
- Add server-side validation and a sanitizer appropriate to the value.
- Save through the
WC_Orderobject for classic checkout, or use the Block field API and its helpers. - Display the value in the admin order editor with escaped output.
- Test a normal checkout, an empty optional value, an invalid value, a failed validation, a guest order, and a logged-in customer order.
- Open the resulting order and verify the value, then check every email or thank-you-page surface where staff or customers are expected to see it.
- Repeat the test after switching between shortcode and Block checkout only if your site intentionally supports both; each path needs its own implementation and test coverage.
Once the checkout type, storage scope, and display surfaces are explicit, custom order fields become a predictable pipeline rather than a collection of disconnected snippets: render or register, validate, sanitize, save, retrieve through the supported API, and escape at output.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
