Table of Contents
To customize the WooCommerce checkout in 2026, pick the block checkout for new builds or the shortcode for legacy themes, then edit fields with the woocommerce_checkout_fields filter, delete fields you do not need, and test a real order end to end. You know it worked when the checkout renders your layout, saves only the fields you kept, and completes a test purchase without PHP notices or failed-order rows.
Checkout Block vs Shortcode
WooCommerce 9.x (current in 2026) ships two checkout front ends. The block checkout (woocommerce/checkout) lives in the editor, is React-driven, and is the default in Storefront and block themes. The classic shortcode [woocommerce_checkout] renders the PHP template templates/checkout/form-checkout.php and is still supported for legacy themes.
Use the block when you want layout control in the Site Editor and future-proofing; use the shortcode when you run a classic theme or heavy PHP field logic. Verify which one you run: edit the Checkout page and look for the block wrapper, or run wp option get woocommerce_checkout_page_id then inspect the post content for wp:woocommerce/checkout.
Pitfall: field PHP filters do not affect the block checkout the same way; the block uses woocommerce_get_editor_blocks_registration and endpoint JSON. Rollback: switch the page back to the shortcode by replacing the block with [woocommerce_checkout] in the editor.
Step-by-Step Customization Process
- Back up the site and put it in staging:
wp db export backup.sqlandwp maintenance-mode activate. - Decide block vs shortcode and set the Checkout page accordingly.
- Add a child theme or mu-plugin file at
wp-content/mu-plugins/checkout-tweaks.phpwith your field filter. - Remove or reorder fields inside
woocommerce_checkout_fields. - Place a test order with a gateway in sandbox mode and confirm the thank-you page.
- Check
WooCommerce > Status > Logsfor fatal errors, then deploy to production.
Using woocommerce_checkout_fields
The woocommerce_checkout_fields filter is the main hook for the shortcode checkout. It receives one array with keys billing, shipping, account, order. Each field is an array with label, placeholder, required, class, priority.
Copy this into wp-content/mu-plugins/checkout-tweaks.php to relabel and drop the company field:
Get a Quote
Email + requirement + budget range — we reply with a quote within 24 hours.
add_filter( 'woocommerce_checkout_fields', 'ro_runok_checkout_fields' );
function ro_runok_checkout_fields( $fields ) {
$fields['billing']['billing_company']['required'] = false;
$fields['billing']['billing_phone']['label'] = 'Mobile number';
$fields['billing']['billing_email']['priority'] = 5;
return $fields;
}
Why: priorities control order, required controls validation. Verify by loading /checkout and seeing the new label and order. Pitfall: caching hides changes — run wp cache flush. Rollback: delete the mu-plugin file or comment out the add_filter line.
For teams comparing build partners, see WooCommerce Development Services: A 2026 Vendor Selection Guide before you hand off custom checkout work.
Removing Unnecessary Fields
To remove a field, unset the key inside the same filter. Do not hide it with CSS only, because WooCommerce still validates it server-side.
add_filter( 'woocommerce_checkout_fields', 'ro_remove_fields' );
function ro_remove_fields( $fields ) {
unset( $fields['billing']['billing_company'] );
unset( $fields['shipping']['shipping_company'] );
unset( $fields['order']['order_comments'] );
return $fields;
}
Verify: the field is gone from the DOM and a POST without it passes validation. If you use the block checkout, remove fields via woocommerce_blocks_checkout_fields or the editor instead. Rollback: restore the unset lines from version control, or remove the filter file.
Layout also matters for conversion; pair field removal with a one-column layout from Reusable Block Patterns That Editors Actually Use to keep the form scannable.
Debugging Failed Orders
Failed orders show in WooCommerce > Orders with status Failed or On hold. Turn on logging at WooCommerce > Settings > Advanced > Features and read wp-content/uploads/wc-logs/.
Common causes in 2026: gateway webhook mismatch after a domain move, a required field you removed still expected by the gateway, or a fatal in a custom validation hook. Reproduce with wp wc shop_order create --status=pending then pay in sandbox.
Check the log name matching the gateway, e.g. stripe-2026-01-15.log. Fix the root cause, then re-run the order. Rollback: set the order status back to Cancelled and refund in the gateway dashboard if money moved.
Frequently asked questions
Does woocommerce_checkout_fields work with the block checkout?
No, not for layout. The block uses its own registration; use woocommerce_blocks_checkout_fields or the Site Editor for block-based stores.
How do I revert a broken checkout edit?
Remove the mu-plugin or child-theme function file you added, flush cache with wp cache flush, and reload the Checkout page.
Where are failed-order logs stored?
In wp-content/uploads/wc-logs/ when WooCommerce logging is enabled under Advanced settings.
Action Checklist
- Confirm block vs shortcode on the Checkout page.
- Add field filters in an mu-plugin, not the parent theme.
- Unset only fields the gateway does not require.
- Place a sandbox test order and read wc-logs.
- Keep a rollback file copy in version control.
Need expert help? See our theme development services for custom WooCommerce checkout builds backed by senior engineers.
