WooCommerce Checkout Blocks: Complete Migration Guide from Classic Checkout

The WooCommerce Checkout Block is no longer an optional experiment, it is the future of WooCommerce checkout, and for many stores, the present. Introduced with WooCommerce 6.x as part of the WooCommerce Blocks plugin, the Checkout Block has matured into a fully-featured, extensible checkout experience that outperforms the classic shortcode-based checkout on nearly every metric: page load speed, mobile conversion rate, developer extensibility, and long-term support trajectory.

Yet many store operators and developers are hesitant to migrate. The classic checkout has been around since WooCommerce 1.0, and the plugin ecosystem around it, checkout field editors, payment gateway hooks, conditional logic plugins, represents years of accumulated customization. Migrating feels risky. But staying on classic checkout increasingly means falling behind on performance, missing compatibility with modern payment integrations, and eventually facing a forced migration anyway as WooCommerce deprecates shortcode-based checkout in future major releases.

This complete guide walks you through everything you need to know to migrate from classic checkout to the WooCommerce Checkout Block safely and successfully: compatibility assessment, field customization, payment gateway support, custom hook equivalents, testing strategy, and rollback procedures. Whether you are migrating a simple store or a heavily customized enterprise checkout, this guide gives you the framework to do it right.

Why Migrate to the WooCommerce Checkout Block?

Before diving into the how, let’s be clear about the why. Understanding the concrete benefits of the Checkout Block helps teams make the business case for migration and sets realistic expectations about the effort involved.

Performance Gains

The Checkout Block is built with React and communicates with the WooCommerce Store API rather than the classic shortcode rendering pipeline. This architecture enables several performance advantages over classic checkout:

• Reduced PHP rendering overhead: Block checkout renders server-side only once; subsequent interactions (address changes, coupon application, shipping rate selection) update via Store API calls without full page reloads
• Fewer JavaScript dependencies: Classic checkout loads jQuery, jQuery UI, and multiple legacy scripts; Block checkout uses modern React with tree-shaking and code splitting
• Better Core Web Vitals: WooCommerce team benchmarks show 15-30% improvement in LCP and CLS on the checkout page when migrating from classic to block checkout
• Eliminated cart fragment polling: Classic checkout repeatedly polls for cart data; Block checkout uses event-driven updates via the Store API

These performance improvements translate directly to checkout conversion rates. A 100ms improvement in checkout page load time correlates with a measurable increase in order completion rates, particularly on mobile devices where network conditions are variable.

Modern Developer Experience

The Checkout Block introduces a proper extension API, the ExtendSchema and registerCheckoutBlock interfaces, that replaces the hodgepodge of PHP hooks and JavaScript overrides used in classic checkout. This means customizations are safer, more predictable, and far easier to maintain across WooCommerce major version upgrades. For the full Store API extensibility picture, see our WooCommerce Store API Developer Guide.

Roadmap Alignment

WooCommerce has been clear in its public roadmap: the Checkout Block is the direction of all future checkout development. New payment integrations, checkout features, and performance improvements are being built exclusively for the block-based checkout. Classic checkout will receive security patches and critical bug fixes but no new features. Migrating now means gaining access to the full future of WooCommerce checkout development rather than waiting for an inevitably more disruptive forced migration later.

Pre-Migration Compatibility Assessment

Before migrating any live store, conduct a thorough compatibility assessment. The Checkout Block is not compatible with all classic checkout customizations, some require updated approaches, and a small number of use cases may not yet have block equivalents.

Payment Gateway Compatibility

This is typically the most critical compatibility factor. Check that your payment gateways support the Checkout Block by verifying their declared support for the blocks feature in their plugin registration. Most major gateways have updated their plugins:

Payment Gateway	Block Checkout Support	Notes
WooCommerce Payments (Stripe)	Full support	Native integration, recommended
Stripe for WooCommerce	Full support	Requires v6.5+ of the Stripe plugin
PayPal Payments	Full support	PayPal Buttons render in block checkout
Square for WooCommerce	Full support	Requires v3.0+
Authorize.Net	Partial	Check plugin changelog for block support date
Amazon Pay	Full support	Requires v2.4+
Klarna	Full support	Native Klarna On-Site Messaging supported
Afterpay/Clearpay	Full support	Block messaging widget included
Custom/legacy gateways	Varies	Must implement IntegrationInterface

For gateways that don’t yet have full block support, the Checkout Block falls back to the classic payment gateway rendering for that gateway only, meaning you can still use most gateways without them fully implementing the block integration, though you miss some UX and performance benefits for that specific gateway.

Hook and Filter Compatibility

Classic checkout relies on dozens of action and filter hooks for customization. Many of these hooks do not fire in block checkout because the block checkout rendering pipeline is fundamentally different. Here is a mapping of commonly used classic checkout hooks and their block checkout equivalents:

Classic Hook	Block Equivalent	Approach
woocommerce_before_checkout_form	No direct equivalent	Use custom block or inner block slot
woocommerce_checkout_fields	Store API checkout fields API	Register fields via PHP checkout fields API
woocommerce_after_checkout_billing_form	Inner block slots	Register custom inner block in billing section
woocommerce_checkout_order_processed	woocommerce_store_api_checkout_order_processed	Same timing, different hook name
woocommerce_checkout_update_order_meta	woocommerce_store_api_checkout_update_order_from_request	Request object replaces POST data
woocommerce_payment_fields	Payment integration components	Gateway must implement block payment component

Plugin Compatibility Checklist

Run through this checklist for each plugin that customizes your checkout:

• Does it use woocommerce_checkout_fields filter? → Needs migration to Checkout Fields API
• Does it use woocommerce_before/after_checkout_form actions? → Needs block slot registration
• Does it add custom payment gateway fields? → Gateway needs block payment component
• Does it use woocommerce_checkout_update_order_meta? → Migrate to Store API order update hook
• Does it inject JavaScript via wp_enqueue_scripts on checkout? → Verify it doesn’t conflict with React rendering
• Does it use WooCommerce session data written before checkout? → Verify session data is accessible via Store API

Setting Up the Checkout Block

Once you’ve completed your compatibility assessment and updated incompatible plugins, you’re ready to set up the Checkout Block. The process is straightforward for most stores.

Replacing the Classic Checkout Shortcode

The classic checkout uses the [woocommerce_checkout] shortcode on a page. To migrate:

• Navigate to your Checkout page in the WordPress block editor
• Remove the Classic Checkout block or shortcode block
• Search for and add the “Checkout” block (from WooCommerce Blocks)
• The block will auto-populate with default inner blocks: Contact Information, Shipping Address, Shipping Options, Billing Address, Order Note, Terms and Conditions, Payment Options, and Order Summary
• Rearrange inner blocks as needed for your checkout flow
• Save and test immediately in a staging environment

Configuring Checkout Block Settings

The Checkout Block has several configurable settings accessible via the block editor sidebar:

• Guest checkout: Enable or require account creation before purchase
• Company field: Show/hide/require company name
• Address line 2: Show/hide optional address field
• Phone number: Show/hide/require phone in billing and shipping
• Order notes: Enable/disable the order note field
• Local pickup toggle: Enable local pickup as a shipping option (requires Local Pickup shipping method)
• Terms checkbox: Link to terms page and configure requirement

These settings replace many of the filter-based configurations used in classic checkout. They are stored as block attributes rather than WooCommerce settings, which means they are versioned with your content and transferable between environments via block content export.

Migrating Custom Checkout Fields

Custom checkout fields are one of the most common customizations and one of the most significant migration challenges. In classic checkout, fields are added via the woocommerce_checkout_fields filter. The Checkout Block replaces this with the WooCommerce Checkout Fields API, introduced in WooCommerce 8.6.

Using the Checkout Fields API

The Checkout Fields API provides a PHP-based method for registering additional fields that appear in the Checkout Block:

<?php
// Register a custom checkout field (WooCommerce 8.6+)
add_action( 'woocommerce_init', function() {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return; // Bail if function not available (old WooCommerce version)
    }

    woocommerce_register_additional_checkout_field(
        array(
            'id'            => 'my-plugin/gift-message',
            'label'         => __( 'Gift message', 'my-plugin' ),
            'location'      => 'order', // 'address', 'contact', or 'order'
            'type'          => 'textarea',
            'required'      => false,
            'attributes'    => array(
                'placeholder' => __( 'Optional message for recipient', 'my-plugin' ),
            ),
        )
    );

    // Custom dropdown field for delivery preference
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-plugin/delivery-preference',
            'label'    => __( 'Delivery preference', 'my-plugin' ),
            'location' => 'order',
            'type'     => 'select',
            'required' => false,
            'options'  => array(
                array( 'value' => '',            'label' => __( 'Select preference', 'my-plugin' ) ),
                array( 'value' => 'morning',     'label' => __( 'Morning (8am-12pm)', 'my-plugin' ) ),
                array( 'value' => 'afternoon',   'label' => __( 'Afternoon (12pm-5pm)', 'my-plugin' ) ),
                array( 'value' => 'evening',     'label' => __( 'Evening (5pm-8pm)', 'my-plugin' ) ),
                array( 'value' => 'leave-door',  'label' => __( 'Leave at door', 'my-plugin' ) ),
            ),
        )
    );
} );

The location parameter controls where the field appears: address for the billing/shipping address forms, contact for the contact information section (email, phone), or order for the additional information section at the bottom of checkout.

Saving Custom Field Data to Orders

Fields registered via the Checkout Fields API are automatically validated and saved to the order, you don’t need separate hooks for sanitization or storage in most cases. The data is accessible via $order->get_meta( '_my-plugin/gift-message' ) after order creation.

For more complex scenarios (conditional validation, cross-field dependencies, server-side async validation), use the checkout validation filter:

<?php
// Validate custom field value server-side
add_action( 'woocommerce_store_api_checkout_update_order_from_request', function( $order, $request ) {
    $fields = $request->get_param( 'additional_fields' );

    // Access the registered field value
    $gift_message = $fields['my-plugin/gift-message'] ?? '';

    if ( strlen( $gift_message ) > 500 ) {
        throw new \Exception(
            __( 'Gift message must be 500 characters or fewer.', 'my-plugin' )
        );
    }

    // Store any custom processing result
    if ( ! empty( $gift_message ) ) {
        $order->update_meta_data( '_has_gift_message', true );
        $order->save();
    }
}, 10, 2 );

Migrating Payment Gateway Integrations

If you have custom payment gateways or heavily customized gateway integrations, migrating them to work with the Checkout Block requires implementing the IntegrationInterface. This is the most technically complex part of the migration for many stores.

The IntegrationInterface

Payment gateways declare Checkout Block support by implementing Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType and registering the integration via the Blocks payment registry. The gateway must provide a React component (via JavaScript) that renders the payment fields in the block checkout:

<?php
use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;

final class My_Gateway_Blocks extends AbstractPaymentMethodType {
    private $gateway;
    protected $name = 'my-gateway';

    public function initialize() {
        $this->settings = get_option( 'woocommerce_my-gateway_settings', [] );
        $this->gateway  = new My_Payment_Gateway();
    }

    public function is_active(): bool {
        return $this->gateway->is_available();
    }

    public function get_payment_method_script_handles(): array {
        wp_register_script(
            'my-gateway-blocks',
            plugin_dir_url( __FILE__ ) . 'js/my-gateway-blocks.js',
            [ 'wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-html-entities' ],
            filemtime( plugin_dir_path( __FILE__ ) . 'js/my-gateway-blocks.js' ),
            true
        );
        return [ 'my-gateway-blocks' ];
    }

    public function get_payment_method_data(): array {
        return [
            'title'       => $this->gateway->title,
            'description' => $this->gateway->description,
            'supports'    => $this->get_supported_features(),
            'publishableKey' => $this->get_setting( 'publishable_key' ),
        ];
    }
}

Testing Your Migration

Never migrate checkout directly on a live store. A structured testing approach ensures you catch all issues before customers encounter them. For broader performance considerations during testing, reference our WooCommerce Performance Checklist to verify checkout performance before and after migration.

Staging Environment Testing Protocol

Set up a staging environment that mirrors production exactly, same plugins, same theme, same WooCommerce version. Then run through this comprehensive test matrix:

• Simple product purchase: Guest checkout, single item, default shipping, primary payment gateway
• Variable product purchase: With specific variation selected at checkout
• Digital product purchase: No shipping step should appear
• Coupon application: Fixed, percentage, and free shipping coupons
• Multiple shipping methods: Rate selection and switching between methods
• Address validation: Invalid addresses, international addresses, address autocomplete if used
• Payment failure handling: Declined card, insufficient funds, 3D Secure challenge
• Order completion: Confirmation email, order status, admin notification
• Custom field capture: All custom checkout fields save to order meta correctly
• Mobile checkout: Test on real mobile devices, not just browser emulation

Rollback Plan

Have a clear rollback plan before going live. The simplest approach is to keep the classic checkout page as a backup:

• Duplicate your classic checkout page and name it “Checkout (Classic Backup)”
• Do not set it as the WooCommerce checkout page, keep it as a draft or private page
• If issues arise after migration, update the WooCommerce checkout page setting to point to the classic backup in under 60 seconds
• Keep the rollback page available for at least 30 days after migration

Common Migration Issues and Solutions

Even with thorough preparation, migrations encounter edge cases. Here are the most common issues teams run into during checkout block migration and how to resolve them.

Custom Fields Not Appearing

If fields added via the Checkout Fields API don’t appear, check: WooCommerce version is 8.6+, the woocommerce_init hook fires correctly, the field ID format uses a namespace prefix (e.g., my-plugin/field-name), and the specified location value is valid. Fields added via the legacy woocommerce_checkout_fields filter will not appear in the block checkout, they must be migrated to the Checkout Fields API.

Payment Gateway Not Showing

If a payment gateway doesn’t appear in the block checkout, it likely hasn’t registered block support. Check the gateway plugin’s version and changelog for block support additions. In the interim, WooCommerce will render a fallback “classic” payment section for non-block-compatible gateways, but the UX is degraded. Contact the gateway plugin developer if block support is absent from a major gateway you rely on.

Shipping Rates Not Calculating

The Checkout Block calculates shipping rates via the Store API after address entry. If rates don’t appear or are incorrect, check: the shipping zone configuration matches the customer’s address, shipping plugins declare Store API compatibility, and no PHP fatal errors are occurring in the rate calculation hooks. Enable WP_DEBUG during testing to surface any hidden errors in shipping rate callbacks.

Order Meta Not Saving

If custom data you previously captured via woocommerce_checkout_update_order_meta is no longer saving, you need to migrate that logic to woocommerce_store_api_checkout_update_order_from_request. This hook fires with the order object and the full REST API request, giving you access to all submitted data including custom extension fields.

Frequently Asked Questions

Will my existing orders be affected by migrating to the Checkout Block?

No. Migrating to the Checkout Block only affects the checkout page experience for new orders. All existing orders, order history, and order data remain completely unchanged. The migration only modifies the page used for checkout going forward, historical data is unaffected.

Can I use the Checkout Block with a custom or page builder theme?

Yes, but with caveats. The Checkout Block works with any theme that supports WordPress blocks (the block editor). However, themes that inject heavy CSS into the checkout page, or page builders that wrap page content in their own container elements, may interfere with the Checkout Block’s styling. Test thoroughly on staging with your actual theme before migrating. Block themes (FSE themes) provide the best compatibility and styling control.

Is there a way to run classic and block checkout in parallel during migration?

Yes. You can create two checkout pages, one with classic checkout and one with the Checkout Block, and use a URL-based or cookie-based A/B testing mechanism to split traffic between them. This approach lets you compare conversion rates between classic and block checkout before committing to the migration. WooCommerce supports setting a custom checkout page URL per-session, which some A/B testing tools leverage for exactly this purpose. Just ensure your analytics are tracking each checkout variant separately so you can make a data-driven decision.

Advanced Checkout Block Customizations

Once the baseline migration is complete, you can take advantage of advanced Checkout Block features that have no classic checkout equivalent. These capabilities represent the real long-term value of the migration beyond simple performance improvements.

Custom Inner Blocks

The Checkout Block supports custom inner blocks, React components registered via the registerCheckoutBlock JavaScript API that appear as blocks within the checkout flow. This is how you can add a loyalty points redemption widget, an upsell offer, a gift wrapping selector, or any other custom UI element directly into the checkout experience without any JavaScript injection hacks.

Custom inner blocks have access to the full @woocommerce/blocks-checkout package, which gives them hooks into the checkout state: cart contents, customer data, shipping rates, payment method selection, and checkout validation lifecycle. This means your custom block can react to customer decisions in real time, for example, showing a loyalty discount only when the order total reaches a threshold, or enabling a specific payment method only for customers in certain regions.

Checkout Validation Hooks

The Checkout Block exposes JavaScript-side validation hooks via __experimentalRegisterCheckoutFilters that allow you to block order submission client-side before the request reaches the server. This is useful for client-side validation of custom fields (preventing a form submission if a required custom field is empty), custom business logic (blocking checkout for customers in restricted regions), or showing interstitial confirmation steps (such as an age verification confirmation).

Combined with the server-side validation available in the Store API checkout endpoint hooks, you have a complete validation pipeline, client-side for immediate user feedback, server-side for authoritative validation before order creation. This dual-layer approach is more robust than classic checkout, which relied entirely on server-side validation with full page reloads on failure.

Order Attribution and Analytics

WooCommerce 8.5+ includes built-in order attribution tracking in the Checkout Block, automatically recording UTM parameters, referrer data, and click source with each order. This data is stored with the order and visible in WooCommerce Analytics, giving you clear visibility into which marketing channels drive purchases without requiring third-party attribution plugins.

This order attribution system is block-only, it is not available in classic checkout. Stores that migrate to the Checkout Block immediately gain access to this marketing attribution data, which can significantly improve the accuracy of channel-level ROI reporting for Google Ads, Meta, email campaigns, and affiliate channels.

Migration Timeline and Planning

A realistic checkout block migration timeline for a moderately customized WooCommerce store looks like this, broken down into phases that minimize risk at each stage:

Phase 1: Assessment (Week 1)

Audit all active plugins for block checkout compatibility. Check payment gateway versions. List all custom hooks and filters in your theme’s functions.php and any custom plugins. Test the Checkout Block on staging in its default configuration to establish a baseline. Document every customization that needs migration and estimate the effort for each.

Phase 2: Development (Weeks 2-3)

Update payment gateway plugins to versions with block support. Migrate custom checkout fields to the Checkout Fields API. Rewrite woocommerce_checkout_update_order_meta hooks to use woocommerce_store_api_checkout_update_order_from_request. Build any required custom inner blocks. Write automated tests for the critical checkout path. Verify all customizations work correctly on staging.

Phase 3: Testing (Week 4)

Execute the full checkout test matrix on staging: every product type, every payment method, every shipping method, with and without coupons, guest and registered customers. Test on multiple real devices (iPhone, Android, iPad). Run a small-scale A/B test if possible to compare conversion rates. Review WooCommerce error logs for any checkout-related warnings. Load test checkout performance to verify the block checkout performs better than or equal to classic checkout under peak load conditions.

Phase 4: Launch (Week 5)

Schedule the migration during a low-traffic period (Tuesday or Wednesday morning, for most stores). Update the WooCommerce checkout page to use the block checkout. Monitor for 30 minutes of live traffic before declaring success. Keep the classic checkout backup page accessible for the next 30 days. Check WooCommerce Analytics daily for the first week to verify order completion rates are stable or improved.

Conclusion

Migrating from classic checkout to the WooCommerce Checkout Block is one of the highest-impact technical changes you can make to a WooCommerce store in 2026. The performance improvements, developer experience gains, and alignment with WooCommerce’s long-term roadmap make it a migration worth prioritizing, even for stores with significant checkout customization.

The key to a successful migration is preparation: audit your current checkout plugins and customizations, map each classic hook to its block equivalent, update incompatible payment gateways before switching, and test comprehensively on staging before going live. With a solid rollback plan in place, the risk of the actual cutover is minimal.

Start with your staging environment today. Run the compatibility checklist, update any plugins that need updating, and build the block checkout alongside your existing classic checkout. By the time you’re ready to go live, you’ll have confidence in every aspect of the new experience, and your customers will notice the difference in speed and smoothness from their very first purchase on the upgraded checkout.

The WooCommerce Checkout Block migration is not a one-day project for a heavily customized store, but it is achievable with a structured four-week plan. The stores that migrate successfully in 2026 are the ones that will be best positioned for the continued evolution of WooCommerce, gaining access to new payment methods, new checkout experiences, and new analytics capabilities as they become available. The investment in migration is really an investment in the long-term competitiveness of your store. Teams that delay the migration until it becomes forced will face the same work under higher time pressure and with fewer options for a careful, phased approach. Start now, do it right, and your checkout will be faster, more extensible, and better supported for years to come.