WooCommerce Checkout Blocks: What Every Store Owner Needs to Know

WooCommerce changed its checkout system. Not a minor update, a fundamental architectural shift from PHP-template-based checkout to a React-powered block checkout built on the Gutenberg block editor. If you have updated WooCommerce recently, you may have already been migrated. If you have not, you will be soon. This guide explains everything you need to know about WooCommerce checkout blocks and the WooCommerce block checkout system: what changed, what it means for your store, what breaks, what improves, and exactly what action you need to take.

This is not a theoretical overview. It covers the practical questions store owners actually face: whether your existing plugins still work, how to customize the block checkout without breaking it, what the performance impact is, and how to handle the edge cases that Woo’s own documentation glosses over.

What Is the WooCommerce Block Checkout?

The block checkout is WooCommerce’s new checkout experience, built entirely in React as a Gutenberg block. It replaces the traditional shortcode-based checkout ([woocommerce_checkout]) and the PHP templates in woocommerce/templates/checkout/ that developers have customized for years.

The shift began in earnest with WooCommerce 8.3, when the block checkout became the default for new installations. As of WooCommerce 9.x, existing stores are prompted to migrate. The old shortcode checkout has not been removed, WooCommerce calls it the “classic checkout”, but it is now officially in maintenance-only mode, meaning it will receive security fixes but no new features.

Here is what the change means in concrete terms:

• Old checkout: PHP template rendered server-side, customized via hooks and template overrides in your theme, styled with CSS targeting WooCommerce’s class structure
• New block checkout: React application rendered client-side after initial PHP handoff, customized via block filters and inner blocks, styled with theme.json or block-specific CSS

The user-facing appearance can be made identical. The developer experience is fundamentally different. And the plugin compatibility implications are significant.

Block Checkout Architecture: What Is Actually Happening

Understanding the block checkout’s architecture helps explain why some things work differently and why your existing customizations may not carry over automatically.

The block checkout is structured as a hierarchy of inner blocks, each responsible for a specific section of the checkout page:

Block Name	Handles	Customizable?
woocommerce/checkout	Outer container	Via block attributes
woocommerce/checkout-fields-block	All form fields wrapper	Limited direct edit
woocommerce/checkout-contact-information-block	Email field	Yes, via inner blocks
woocommerce/checkout-shipping-address-block	Shipping address fields	Field visibility settings
woocommerce/checkout-billing-address-block	Billing address fields	Field visibility settings
woocommerce/checkout-shipping-methods-block	Shipping method selection	Via shipping zones
woocommerce/checkout-payment-block	Payment method selection	Via payment gateway integration
woocommerce/checkout-order-summary-block	Order summary sidebar	Can add inner blocks
woocommerce/checkout-actions-block	Place Order button	Limited

Each block can be moved, hidden, or configured within the block editor. You can drag the order summary above the form fields, remove the “Additional information” block, or reorder sections, all without writing code. This is the core UX improvement over the old template system, where reordering sections required PHP hook priority manipulation.

However, the block system also means that hooks targeting the old PHP checkout templates do not fire in the block checkout. The action hooks woocommerce_before_checkout_form, woocommerce_checkout_before_customer_details, woocommerce_checkout_billing, and dozens of others simply do not exist in the block checkout’s rendering cycle.

Plugin Compatibility: What Works, What Does Not

This is the most practically important section of this guide. The block checkout breaks a significant number of plugins that hooked into the classic checkout’s PHP rendering pipeline. Before migrating, you need to know which of your plugins are compatible.

Payment Gateway Compatibility

Payment gateways require specific integration work to appear in the block checkout’s payment block. Gateways that have not added this integration will still work, they appear as a fallback option, but they may not render correctly or may require the customer to complete payment on a redirected page rather than inline.

Gateways with confirmed block checkout support as of early 2026:

• WooCommerce Payments (WooPayments), full native support
• Stripe for WooCommerce, full block checkout integration
• PayPal Payments (official), full support with express checkout buttons
• Square for WooCommerce, block checkout support in recent versions
• Klarna Payments, block checkout support added 2024
• Authorize.Net (CIM), partial support; some features require classic checkout

Older or less-maintained gateways, especially those from smaller developers or those that have not been updated in 12+ months, are the highest risk. Test each one explicitly before migrating.

Checkout Customization Plugins

Plugins that add fields to checkout, reorder sections, or inject content into the checkout form are the most commonly affected category. Classic examples:

Plugin Type	Block Checkout Compatibility	Status
Checkout Field Editor (WooCommerce)	Partial	Custom fields need migration to Additional Fields API
WooCommerce Product Add-Ons	Yes	Updated for block checkout support
Checkout Address Autocomplete	Varies	Depends on implementation method
Order Delivery Date plugins	Partial	Some updated, some still hook into classic checkout
Fee plugins (order-level fees)	Partial	Requires block checkout-specific hooks
Upsell plugins (checkout upsells)	Varies	Those using hooks may not display

For upsells and cross-sells at checkout, the approach changes in the block checkout. Instead of using PHP hooks to inject content, you use the Order Summary block’s inner block capability or WooCommerce’s __experimentalRegisterCheckoutFilters JavaScript API. The complete guide to WooCommerce upsells and cross-sells covers the modern techniques that work with both classic and block checkout.

How to Check Your Plugin Compatibility

The most reliable method is to test on a staging environment before migrating production. Follow this process:

1. Clone your production site to a staging environment
2. Enable the block checkout on the staging site (WooCommerce > Settings > Advanced > Checkout page, then edit the page and switch to the block checkout template)
3. Run a complete test checkout for each payment method you offer
4. Check that custom checkout fields appear and save correctly
5. Verify that any checkout upsell or order bump content displays
6. Confirm order confirmation emails contain all expected data
7. Test with a WooCommerce-compatible store performance plugin to check for any caching issues

Customizing the Block Checkout Without Writing Code

One of the genuine advantages of the block checkout is that basic customization is accessible to non-developers through the block editor. Here is what you can do without touching code:

Reordering Checkout Sections

Navigate to WooCommerce > Settings > Advanced > Checkout, then click the edit link for your checkout page. In the block editor, you can drag and drop the inner blocks to reorder sections. Move the order summary to the left column, put contact information after shipping, or move the payment block above the billing address, all with drag and drop.

Hiding Optional Sections

Select any inner block and use the block settings panel (right sidebar) to configure visibility. The “Additional Information” block can be removed entirely if you do not use order notes. The “Policies” block (showing shipping and return policy links) can be toggled off. The company field in the address blocks can be set to hidden, optional, or required via the block settings.

Adding Content to the Order Summary

The order summary sidebar accepts inner blocks. You can add a paragraph block with your store’s guarantee or trust signal text, add an image block for a security badge, or add a HTML block for custom content. This replaces the common pattern of using woocommerce_review_order_before_submit PHP hooks to add trust content near the payment section.

Customizing the Block Checkout With Code

For developers, the block checkout introduces a new API surface. Classic PHP hooks are replaced by a combination of server-side block registration and client-side JavaScript filters.

Adding Custom Fields via the Additional Fields API

WooCommerce 8.6+ introduced the Additional Fields API, which is the official way to add custom fields to the block checkout. The API allows you to register fields that appear in the contact information section, billing address, or shipping address, and that save to order meta correctly.

Register a custom field in PHP:

add_action( 'woocommerce_init', function() {
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my_plugin/gift_message',
            'label'    => 'Gift message',
            'location' => 'contact',
            'required' => false,
            'type'     => 'textarea',
            'attributes' => array(
                'placeholder' => 'Enter a message for the recipient...',
                'rows'        => '3',
            ),
        )
    );
} );

This registers a gift message textarea in the contact information section of the block checkout, handles validation and sanitization, and saves the value to order meta automatically. The same API supports text, textarea, checkbox, and select field types. Retrieving the saved value from an order uses standard WooCommerce order meta methods.

Checkout JavaScript Filters

For more advanced modifications, WooCommerce exposes JavaScript filters via its @woocommerce/blocks-checkout package. Common use cases include modifying the cart item data displayed in the order summary, adding validation rules, and injecting content into specific checkout locations.

Example: add a custom notice above the payment section:

const { registerCheckoutFilters } = window.wc.blocksCheckout;

registerCheckoutFilters( 'my-plugin', {
    additionalCartCheckoutInnerBlockTypes: ( value, extensions, args ) => {
        if ( args?.block === 'woocommerce/checkout-payment-block' ) {
            return [ ...value, 'core/paragraph' ];
        }
        return value;
    },
} );

Performance Impact of the Block Checkout

The block checkout has a meaningfully different performance profile than the classic checkout. Understanding this helps you configure caching correctly and avoid the performance pitfalls that affect some stores after migration.

What Gets Better

• Reduced full-page reloads: The block checkout handles most interactions (updating quantities, applying coupons, changing shipping methods) without a full page reload, using React’s component state management. This significantly reduces perceived latency during checkout.
• Express payment buttons: Apple Pay, Google Pay, and PayPal Express appear above the form via the Express Payment Block, no separate plugin required for supported gateways. These reduce checkout steps for eligible customers.
• Better error recovery: Payment errors are handled client-side without losing form data. In the classic checkout, a payment failure often cleared the entire form.

What Gets More Complex

• Initial JavaScript payload: The block checkout loads a larger JavaScript bundle than the classic checkout. On a well-optimized server this is negligible; on slow hosting it can add 200–400ms to Time to Interactive. Ensure your hosting has server-level caching and consider a CDN for static assets.
• Caching configuration: The checkout page should never be cached for logged-in users or for any user with cart contents. Most caching plugins handle this correctly, but verify your caching rules explicitly after migrating. The guide to WordPress caching for WooCommerce covers the correct checkout page exclusion settings for each major caching plugin.
• REST API dependency: The block checkout communicates with WooCommerce’s Store API via REST endpoints. If your hosting environment has REST API restrictions or if a security plugin blocks REST requests incorrectly, the checkout will break silently. Test REST API availability explicitly after migration.

Migrating From Classic to Block Checkout: Step-by-Step

If you are still running the classic checkout, here is the migration process that minimizes risk.

1. Audit your current plugins: List every plugin that touches checkout behavior. For each one, check the plugin’s changelog or support forum for “block checkout” mentions. Contact the developer if documentation is unclear.
2. Create a staging site: Never migrate checkout on production without a staging test. If your host does not provide staging environments, use a local copy via LocalWP.
3. Switch to block checkout on staging: Edit your checkout page in WordPress. Replace the classic [woocommerce_checkout] shortcode with the Checkout block. Alternatively, use WooCommerce’s built-in migration tool under WooCommerce > Extensions > Block Checkout.
4. Test every payment method: Run actual test transactions for each active payment gateway. Use test mode/sandbox where available. Verify the order appears correctly in WooCommerce orders with all expected data.
5. Test custom fields: If you have custom checkout fields, verify they appear, accept input, validate correctly, and save to order meta. Check that the data appears in order emails and the order admin view.
6. Test on mobile: The block checkout’s layout is responsive by default, but custom additions can break mobile layout. Test on iOS Safari and Android Chrome specifically.
7. Monitor conversion rate post-launch: After migrating production, watch your checkout completion rate for the first week. A meaningful drop (more than 3–5% relative) suggests a compatibility issue that needs investigation.

Block Checkout and WooCommerce Cost: The Bigger Picture

The block checkout transition is part of a larger WooCommerce trajectory toward a more modern, JavaScript-forward architecture. Understanding that trajectory helps store owners make better platform decisions. The block checkout is specifically designed to support features like express payments, one-page checkout, and native Apple Pay/Google Pay integration, features that previously required expensive third-party plugins or custom development.

If you are evaluating whether to stay on WooCommerce or consider other platforms, the block checkout’s express payment integration is a meaningful feature parity gain against hosted platforms. Shopify’s checkout has offered express payment buttons for years; WooCommerce now offers comparable functionality natively. For a full cost comparison including payment processing options, see the WooCommerce vs Shopify total cost breakdown.

Block Checkout and Conversion Rate Optimization

Beyond compatibility and migration concerns, the block checkout opens new conversion rate optimization (CRO) opportunities that were not easily achievable with the classic checkout. Store owners who approach the migration as a CRO opportunity rather than just a technical obligation tend to see better outcomes.

Express Payment Buttons

The Express Payment Block displays Apple Pay, Google Pay, and PayPal One Touch buttons at the top of the checkout, before the customer fills in any form fields. For eligible customers on compatible devices (most modern smartphones and browsers), this reduces checkout to 2–3 taps. Studies from multiple payment processors show 10–30% higher conversion rates for express payment methods compared to traditional form-fill checkout.

These buttons are only available in the block checkout. If you are on the classic checkout, you cannot offer Apple Pay or Google Pay natively without a third-party plugin, and even then the integration is less reliable. This alone is a compelling migration reason for mobile-heavy stores.

Coupon Code Field Placement

The classic checkout displays the coupon code field prominently on the checkout page, which research suggests triggers coupon-seeking behavior, customers leave to find a coupon code and do not return. The block checkout allows you to remove the coupon field from checkout entirely (for stores where checkout is not the right moment to apply discounts) or move it to a less prominent location within the order summary block.

You can also control coupon visibility with a block filter, showing the coupon entry only after the customer has started filling in payment details, further along in the commitment funnel. This is a meaningful CRO lever that required custom PHP in the classic checkout.

Optimized Mobile Layout

The block checkout is built mobile-first with React’s responsive rendering. On small screens, it defaults to a single-column layout with the order summary collapsed (expandable via a tap). Shipping and payment sections are fully keyboard-navigable and touch-optimized. For stores where 40–60% of traffic is mobile (increasingly common), the block checkout’s mobile experience is materially better than the classic checkout, which required extensive CSS customization to render correctly on small screens.

Real-Time Validation

The block checkout validates form fields in real time as customers type, rather than waiting for form submission. Invalid email addresses, incomplete phone numbers, and missing required fields are flagged immediately with contextual error messages positioned next to the relevant field. This reduces form submission errors and the frustration that drives abandonment. In the classic checkout, inline validation required third-party plugins or custom JavaScript.

Troubleshooting Common Block Checkout Issues

After migration, certain problems appear commonly across WooCommerce stores. Here are the most frequent issues and their solutions.

Payment Gateway Not Appearing

If an enabled payment gateway does not appear in the block checkout’s payment section, it typically means the gateway has not registered itself with WooCommerce’s block checkout API. First, check for a plugin update, many gateways added block checkout support in 2024. If no update is available, the gateway will appear in a fallback “Other payment methods” section that uses an iframe to the classic checkout form, which works but is less seamless. Contact the gateway developer to request block checkout support if this is a problem for your store.

Custom Fields Not Saving

Custom checkout fields added via PHP hooks (using woocommerce_checkout_fields filter, for example) will not appear or save in the block checkout. The woocommerce_checkout_fields filter only applies to the classic checkout’s PHP rendering. You must migrate custom fields to the Additional Fields API (available in WooCommerce 8.6+). If you are on WooCommerce 8.5 or earlier, update WooCommerce first, then migrate your field registration code to use woocommerce_register_additional_checkout_field().

Order Summary Not Showing Updated Prices

If the order summary does not update when customers apply coupons, change shipping methods, or modify their cart, this is typically a caching issue. Your caching plugin is likely serving a cached version of the checkout page or the Store API responses. Verify that your checkout page URL is in your caching plugin’s exclusion list, and that the Store API endpoints (/wp-json/wc/store/v1/) are excluded from any proxy or server-level cache. The store API must always be served dynamically.

Frequently Asked Questions

Will my classic checkout theme template overrides still work?

No. Template overrides in your-theme/woocommerce/checkout/ apply to the classic checkout only. If you switch to the block checkout, these template files are ignored. Any customizations you made in those files need to be recreated using the block editor’s visual tools, the Additional Fields API, or JavaScript filters. This is the most common source of “things look wrong after migration” issues. Before migrating, document every customization in your classic checkout templates and plan how to recreate each one using block checkout methods.

Can I keep using the classic checkout permanently?

Yes, but it is not recommended long-term. WooCommerce has confirmed the classic checkout remains in the codebase for “the foreseeable future” and will continue to receive security patches. However, new features, including future payment integrations, express payment button types, and checkout UX improvements, will be built exclusively for the block checkout. If you delay migration, you will eventually find your classic checkout falling behind both in features and, potentially, in compatibility with newer versions of payment gateway plugins that prioritize block checkout integration in their development roadmap.

Does the block checkout work with page builders like Elementor or Divi?

The block checkout must be placed on a standard WordPress/Gutenberg page, it cannot be placed inside an Elementor or Divi template. If your checkout page is built with a page builder, you have two options: create a new standard WordPress page with the block checkout and redirect your checkout URL to it, or keep the classic checkout shortcode on your page builder-built checkout page. Many stores that use page builders for other pages keep a plain WordPress page specifically for checkout, which is the recommended approach when migrating to the block checkout.

The Bottom Line for Store Owners

The WooCommerce block checkout is where the platform is going. It is not a question of whether to migrate but when. The practical answer for most store owners:

• New stores: Use the block checkout from day one. The classic checkout has no advantage for stores that have not built customizations on it.
• Stores with minimal checkout customization: Migrate now. The process is low-risk, and you benefit immediately from express payments and improved error handling.
• Stores with heavy checkout customization: Audit plugins, test thoroughly on staging, plan for custom field recreation using the Additional Fields API. Budget 4–8 hours of developer time for migration if you have complex customizations.
• Stores with unmaintained plugins in the checkout flow: Resolve the plugin situation first, either find maintained alternatives or get the plugins updated, then migrate.

The WooCommerce checkout blocks system represents a genuine improvement in checkout flexibility and feature capability. The migration friction is real but manageable. Done with proper testing and planning, the switch improves your store’s checkout experience and positions it for the new payment features WooCommerce will continue to ship exclusively to the block checkout going forward.