---
title: "Move WooCommerce to the Checkout Block Safely: A Step-by-Step Guide"
description: "Switch a WooCommerce store from the shortcode checkout to the Cart and Checkout blocks: check gateways, move custom fields and hooks, test, and roll back."
url: https://adnanshawkat.me/blog/move-woocommerce-to-checkout-block/
---

[← All posts](https://adnanshawkat.me/blog/)

# How to Move WooCommerce to the Checkout Block Without Breaking Checkout

12 November 2026 · WooCommerce · WordPress · Checkout · Maintenance

![An old paper checkout form with crossed-out boxes and loose puzzle pieces, with an arrow to a clean checkout built from stacked blocks, next to a shopping cart and a checklist](https://adnanshawkat.me/images/blog/woocommerce-checkout-block-migration.webp)

If your WooCommerce store was set up before late 2023, your checkout page probably still runs on the `[woocommerce_checkout]` shortcode. New stores haven’t worked that way since WooCommerce 8.3, which made the Cart and Checkout blocks the default.

The block checkout is faster to load, easier to style in the editor, and it’s where WooCommerce is putting new checkout features. The catch is that it’s built differently. It talks to the Store API in the browser instead of rendering a PHP template, so a lot of the code that customised the old checkout simply doesn’t run anymore.

The switch itself is a page edit. The risk is in the gateways, fields and hooks your store quietly depends on. Here’s how I move client stores over.

## What actually changes

The shortcode checkout is a PHP template. Plugins and themes change it with hooks like `woocommerce_checkout_fields`, `woocommerce_review_order_before_payment` or `woocommerce_after_order_notes`, and with template overrides in `your-theme/woocommerce/checkout/`.

The Checkout block is a React app. It renders in the browser and sends the order through the Store API. That means:

-   Most checkout template hooks don’t fire, so anything printed through them disappears
-   Theme overrides of `checkout/form-checkout.php` and friends are ignored
-   Fields added through `woocommerce_checkout_fields` won’t show up
-   Payment gateways need their own block integration, or they won’t appear as an option

Code that runs after the order exists, like order status hooks and emails, mostly keeps working. One exception: `woocommerce_checkout_order_processed` doesn’t fire on the block checkout, which uses `woocommerce_store_api_checkout_order_processed` instead. Beyond that, it’s the checkout form itself you need to audit.

## Step 1: Check what you’re running

Open the checkout page in the editor. If you see a single Shortcode block or a Classic Checkout block, you’re on the old checkout. If you see Contact information, Shipping address and Payment options as separate inner blocks, you’re already on the block checkout.

Do the same for the cart page. The Cart block and the Checkout block are separate switches, and it’s best to move them together so the experience is consistent.

## Step 2: Make a staging copy

Same rule as any checkout change: never try it first on the live store. Clone it to staging, turn off outgoing email, and put every payment gateway in test or sandbox mode.

Take a full backup of production too, and write down the current checkout page content so you can put it back in seconds.

## Step 3: Check payment gateways and checkout plugins

Payment gateways are the most common blocker. Stripe, PayPal Payments, WooPayments and the other big gateways all support the block checkout, but older or regional gateways sometimes don’t. A gateway without block support just doesn’t show up, which is the worst kind of failure because nothing errors.

On staging, add the Checkout block to a test page and look at the payment options. Anything missing needs an update, a different gateway, or a reason to stay on the classic checkout for now.

Then list every plugin that touches the checkout: field editors, delivery date pickers, gift messages, tipping, upsells, address validation, tax ID fields. When you select the Checkout block, the editor sidebar flags plugins that haven’t declared block support. Check each one’s changelog. Most maintained plugins added support a while ago.

## Step 4: Move your custom code

Search your theme and custom plugins for the patterns that won’t carry over:

```
grep -rnE "woocommerce_checkout_fields|woocommerce_(before|after|review_order)_|woocommerce_form_field|checkout/form-" \
  wp-content/themes/your-theme wp-content/plugins/your-plugin
```

Each hit needs a block-checkout equivalent:

-   Extra fields added with `woocommerce_checkout_fields` move to the Additional Checkout Fields API, `woocommerce_register_additional_checkout_field()`, which places them in the contact, address or order section and saves them to the order for you
-   Notices or text printed with `woocommerce_review_order_before_payment` and similar hooks become an inner block, a filter on the block, or simple block content added in the editor
-   Validation in `woocommerce_checkout_process` needs to move to the Store API side, for example with the `woocommerce_store_api_checkout_update_order_from_request` action
-   Template overrides in `checkout/` usually become editor changes, since layout and copy can now be edited directly in the block

If you maintain a plugin that works with the new checkout, declare it so WooCommerce stops flagging it:

```
add_action( 'before_woocommerce_init', function () {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
    }
} );
```

## Step 5: Switch on staging and test

Replace the shortcode on the cart and checkout pages with the Cart and Checkout blocks. Then test the paths that make money:

-   Place an order with every payment method you offer, including a failed card
-   Try guest checkout and logged-in checkout, and account creation if you allow it
-   Check shipping rates for a few addresses, plus local pickup if you use it
-   Apply a coupon and check taxes on the totals
-   Confirm every custom field shows up, validates, and lands on the order in admin and in the order emails
-   If you sell subscriptions, place a subscription order and run a renewal
-   Check anything downstream that reads orders: shipping labels, accounting sync, CRM, analytics purchase events

Keep `debug.log` and the browser console open. Errors on the block checkout tend to show up in the console first.

## Step 6: Do it on production

When staging is clean, make the same page change on production during a quiet hour and place a real low-value order with each main gateway. Watch orders closely for the next few days, especially for missing field data and failed payments.

## Rolling back

If something you missed breaks, rolling back is quick. Select the Checkout block and use the option to switch to the classic checkout, or put the `[woocommerce_checkout]` shortcode back on the page. Do the same for the cart. Orders aren’t stored differently, so nothing is lost either way.

## FAQ

### Is the Checkout block required in WooCommerce?

No. The classic shortcode checkout is still supported, but the blocks have been the default for new stores since WooCommerce 8.3 and new checkout features are built for them first.

### Why doesn’t my payment gateway show up on the Checkout block?

The gateway needs a block integration to appear. Update the gateway plugin, check its documentation for block support, or switch back to the classic checkout until it’s available.

### What happens to fields added with woocommerce\_checkout\_fields?

They don’t show on the Checkout block. Move them to the Additional Checkout Fields API, or use a field plugin that supports the block checkout.

### Will switching affect existing orders?

No. The change is only to the cart and checkout pages. Existing orders, and how they’re stored, stay the same.

## Need a hand?

If your checkout has years of custom fields, hooks and gateway tweaks, I can audit it, rebuild the custom bits for the block checkout, and run the switch with you. [Get in touch](https://adnanshawkat.me/contact/) or see my [services](https://adnanshawkat.me/services/).

Agency with several client stores still on the shortcode checkout? [Betatech](https://betatech.co) works as your white-label WordPress team, NDA included.

[← Previous post**Rebuy Is Off the Shopify App Store: What Happened and What to Do**](https://adnanshawkat.me/blog/rebuy-removed-from-shopify-app-store/)

## Questions about this post?

Or a store that needs the same kind of work? Send me a message and I’ll reply within one business day.

[Contact me →](https://adnanshawkat.me/contact/) [See services](https://adnanshawkat.me/services/)