Custom fields on the WooCommerce Checkout block: why your old snippet does nothing

If you added a checkout field using woocommerce_checkout_fields or printed one using woocommerce_after_order_notes, you may have noticed it isn't appearing in newer WooCommerce stores. This is because the store likely utilizes the Checkout block, introduced in WooCommerce 8.3 (November 2023). This block creates its form in React and communicates with the Store API, causing most classic checkout hooks to not function.

While WooCommerce's compatibility table lists woocommerce_after_order_notes, woocommerce_before_order_notes, and woocommerce_review_order_before_submit as unsupported, woocommerce_checkout_fields is only partially supported. Another validation issue arises with woocommerce_checkout_process, which doesn't trigger, resulting in the field not being saved, nor any error displayed.

To address this, use the Additional Checkout Fields API, introduced in WooCommerce 8.9. Register the field by adding the following code to a plugin (not functions.php) to ensure it persists through theme changes. The ID must include a namespace (namespace/name); otherwise, registration fails with a _doing_it_wrong notice. The location setting determines where the field is stored—order for order-specific fields and contact or address for customer account or billing/shipping fields.

Choose the appropriate field type (text, select, checkbox, or date) from WooCommerce 11.2. Register the field using the woocommerce_init hook or later, as registering before after_setup_theme triggers a notice. When validating, ensure to do so after sanitize_callback, as validate_callback runs after sanitization. For cross-field validation, add a custom action and update the WP_Error object provided.

Do not return a new WP_Error object, as this does nothing. If other plugins added validations, check the specific error name they provided. In the admin order screen, thank-you page, and order emails, the field appears without additional code. In your custom code, fetch the field value using WooCommerce's helper class instead of raw meta keys.

Use the 'other' group for contact and order fields, and 'billing' or 'shipping' for address fields. Note that fields registered via this API do not appear on the shortcode checkout, so if you need to modify or remove core fields, use a type not listed (file upload, radio, textarea), or show an address field for only one address.

Remember, fields added with this API won't display on the shortcode checkout, so classic hooks are still necessary for such modifications.