WooCommerce Cart and Checkout Blocks: The Migration Guide

by Francis Rozange | Oct 2, 2026 | WooCommerce

An old glass archway replaced, block by block, by a structure of glowing cubes

Since November 2023, a new WooCommerce store starts with the Cart and Checkout blocks. Nearly three years later, most existing stores still run the old checkout page, built with shortcodes. WooCommerce acknowledged it itself in spring 2025: adoption remains lower than expected.

That lag has solid reasons. The blocks rest on a different architecture, part of the PHP customizations do not carry over, and some payment or field plugins do not keep up. Migrating without preparation risks a checkout page with no payment method, the worst possible screen for a store.

This guide explains what changed with WooCommerce 8.3, how to tell what your store uses, the role of the Store API, the plugin audit, custom fields, moving customizations, step-by-step migration, block settings and rolling back. The information matches WooCommerce 11.1.2, the current version in October 2026, with version 11.2 due the week of October 6. For conversion work itself, our guide to WooCommerce checkout optimization takes over.

What WooCommerce 8.3 changed, and what it did not

New stores: blocks by default

WooCommerce 8.3 shipped on November 16, 2023, after a two-day delay. Since then, a new installation creates its Cart and Checkout pages with the blocks, and, with a block theme, a block-based order confirmation template. The blocks are part of WooCommerce core: the separate WooCommerce Blocks plugin was permanently closed on wordpress.org in February 2024, and there is nothing to install.

Existing stores: nothing moves on its own

A store updated to 8.3 or later keeps its checkout page. WooCommerce said so from the announcement, and has confirmed it since: shortcodes remain supported for existing stores. The documentation recommends the blocks, while acknowledging that the shortcode version is sometimes more compatible with plugins.

No end date has been announced for the classic checkout, which still receives fixes in the 11.x releases. New features land on the block side first, though, and some only exist there.

Shortcodes and blocks: two architectures

The classic checkout rests on PHP templates and hooks, the attachment points where plugins add code. The blocks rest on a React interface that talks to the Store API, a WooCommerce programming interface. Core inner blocks are locked: a merchant can reorder some sections, but not delete them, except for the coupon form.

The My Account page has no block equivalent. It stays a shortcode, whichever checkout page you choose.

Finding out what your store runs today

Assigned pages and their content

The Cart and Checkout pages are assigned under WooCommerce, Settings, Advanced, in the page setup section. Open each of them in the editor. A

Empty cartYour cart is empty for now.
Your cart is empty. Browse the catalog, add an item, then come back here to complete your order.
 Browse the catalog My account
 Instant downloads after every paid order.
 License keys delivered with licensed products.


Empty cartYour cart is empty for now.
Your cart is empty. Browse the catalog, add an item, then come back here to complete your order.
 Browse the catalog My account
 Instant downloads after every paid order.
 License keys delivered with licensed products.

shortcode signals the classic version. A Cart or Checkout block signals the block version.

On the command line, two standard WP-CLI commands are enough: the first gives the checkout page ID, the second shows its content, replacing 12 with the ID returned.

wp option get woocommerce_checkout_page_id
wp post get 12 --field=post_content

Block themes

With a block theme, the block may live in a Site Editor template, “Page: Checkout” or “Page: Cart”, rather than in the page itself. WooCommerce checks those templates first. Our guide to Full Site Editing and theme.json explains how these templates work.

The status report, under WooCommerce, Status, also flags a page that contains neither the expected shortcode nor the expected block. After a rollback, the page contains a special block that wraps the classic shortcode: it counts as a classic checkout.

The Store API, the engine under the blocks

A public interface by design

The Cart and Checkout blocks do not talk to PHP directly. They query the Store API, a public, unauthenticated REST interface that exposes the cart, checkout, products and a few other resources. Its documentation states that it gives no access to sensitive store data or to other customers’ information.

Write requests require a security token, sent in a header, or a cart token for headless storefronts. Rate limiting exists, off by default. Since WooCommerce 9.6, an option in the advanced features limits checkout attempts to three per minute, a useful protection against stolen card testing.

Why your classic rules do not protect it

The Store API enforces its own rules. A business rule written for the classic cart does not apply to it. WooCommerce gives the example itself: the woocommerce_update_cart_validation filter, used to cap quantities, only applies to the shortcode cart. The Cart block and any Store API client bypass it.

WooCommerce 11.2 adds an equivalent filter on the Store API side, woocommerce_store_api_cart_item_quantity_validation, which returns an error instead of displaying a notice. Even after the update, a limit written the old way only protects the shortcode cart: you need to add a callback on the new filter, which returns an error, and check the first add to cart with woocommerce_store_api_validate_add_to_cart.

Extending the Store API

A plugin that needs to pass its own data to the cart or checkout no longer goes through display hooks. It extends the Store API schema, with the woocommerce_store_api_register_endpoint_data() function, and can trigger a server-side update from the browser through a callback registered with woocommerce_store_api_register_update_callback().

This interface is also getting faster. Since WooCommerce 11.1, block types are no longer registered on requests to the Store API or the REST API, which makes them, according to WooCommerce, 30 to 42% faster. A filter lets you restore the old behavior if a plugin depends on it.

The real case: when the Store API showed guest orders

The Store API runs the blocks, but it also answers on every WooCommerce store, like an entrance that is always open. The December 2025 episode made that very concrete. It is documented by WooCommerce, by GitHub’s security lab, by WPScan and by the wordpress.org forums.

The flaw

The Store API includes a route that returns an order from its number. Its documentation promises that it cannot be used to look up other customers’ orders. Yet for a logged-in user, the check skipped the order key and billing email verification.

At the same time, WooCommerce’s own capability check granted any logged-in user the right to pay for an order, as long as the order was not tied to an account, which is the case for every guest order. The result: any logged-in customer could read any guest order by guessing its number, and order numbers are easy to guess.

The exposed data included names, email addresses, phone numbers, shipping and billing addresses, payment method type and items purchased. No card data was involved. The flaw affected WooCommerce 8.1 to 10.4.2, about two years of releases.

Four days, every version since 8.1

The discovery came from an artificial intelligence agent built by the GitHub Security Lab, which researchers Man Yue Mo and Peter Stöckli had pointed at WooCommerce’s code, the first online store software on their list. The agent quickly found a way for a logged-in customer to view all guest orders. The report reached WooCommerce on December 18, 2025, through Automattic’s bug bounty program.

On December 22, WooCommerce released fixes for every affected branch, from 8.1 to 10.4. The team worked with the wordpress.org plugins team to update affected sites automatically, and stores hosted by Automattic were patched outright. WooCommerce rated the flaw critical, and said it had seen no exploitation outside its own testing. The GitHub and WPScan databases score it 6.5 out of 10, a medium severity.

The forced update debate

The same day, on the wordpress.org forum, a user running several sites, who banned all automatic plugin updates, asked why WooCommerce had updated on all of them. Nadir Seghir, a WooCommerce engineer, explained that WooCommerce had requested a forced security update, something that almost never happens outside a security risk.

Samuel Wood, a wordpress.org administrator, explained that WordPress installs these security updates by default, unless automatic updates are turned off through constants in wp-config.php. Four days later, another user, who manages a client’s store, regretted an update imposed just before Christmas, without notice.

On March 6, 2026, GitHub’s lab published its detailed advisory, and the GitHub blog explained that the same agent later found flaws of the same kind in other commerce platforms, including Spree. Our article on WordPress vulnerabilities by the numbers puts this kind of episode in context.

What it changes for a migration

The most useful lesson is counterintuitive. No source limits the flaw to stores using the Checkout block: the proof of concept called the Store API directly. Going back to shortcodes therefore does not switch off the Store API, which is part of WooCommerce core and answers on every store.

The combination that served as the precondition, guest checkout plus open customer registration, is common. Migration or not, the real protection is keeping WooCommerce up to date, and testing business rules against the Store API, not only against the checkout page.

A glowing glass gateway left open, crossed by beams from every direction

Auditing your plugins before switching

Payment methods

A payment method must register on the browser side and on the server side to appear in the Checkout block. Without that integration, it simply disappears. If no compatible method is active, the customer sees a message saying no payment methods are available.

The major gateways, WooPayments, Stripe, PayPal Payments, Square, Mollie or Klarna, support the blocks. PayPal Payments’ wordpress.org listing still calls that support experimental, while its marketplace page declares it compatible: test it carefully. Our comparison of the best WooCommerce payment gateways covers each of them.

The incompatible plugins notice

In the editor, when an active plugin does not support the block, a notice appears in the sidebar, with a button that switches the page back to the classic checkout in one click, with undo available. Since WooCommerce 10.7, a notice also appears on the public page, to administrators and shop managers.

Caution: only plugins that carry the “WC tested up to” header and explicitly declare themselves incompatible trigger the notice. A silent plugin can break checkout without any warning. Payment methods without an integration are flagged in every case.

Field editors, page builders and checkout replacements

Field editors are a frequent obstacle. ThemeHigh’s Checkout Field Editor supports both checkouts, but with separate configurations: fields created for the classic checkout do not work in the block, and vice versa. WP Desk’s Flexible Checkout Fields needs a separate product for blocks.

Page builders add their own layer. Elementor stated in 2024 that the Cart and Checkout blocks were incompatible with its editor, and recommended its own widgets. Plugins that replace the checkout page entirely, such as CheckoutWC, Fluid Checkout or FunnelKit, make the block question largely moot.

Subscriptions and legal requirements

Plugins that touch the core of the journey deserve a dedicated test. WooCommerce Subscriptions declares itself compatible with the Cart and Checkout blocks. Germanized, widely used for the legal requirements of German stores, supports both checkouts, and its changelog shows regular fixes on the block side.

For these plugins, declared compatibility does not replace a full run: a subscription renewal, a required consent checkbox or a missing legal notice only show up when you place a real order on the staging copy.

Custom fields: the Additional Checkout Fields API

Three locations, a few types

In the Checkout block, you no longer add fields by editing the fields array in PHP. WooCommerce provides a dedicated API, introduced in version 8.5 and stable since 8.9, in May 2024. A field shows in only one of three locations: contact, address or order information.

The choice of location decides the storage. An address field is asked twice, for billing and shipping. A contact field is saved to the customer’s account and to the order. An order field is saved to the order only.

add_action( 'woocommerce_init', function () {
	woocommerce_register_additional_checkout_field(
		array(
			'id'       => 'my-plugin/vat-number',
			'label'    => 'VAT number',
			'location' => 'contact',
			'type'     => 'text',
			'required' => false,
		)
	);
} );

In version 11.1.2, three types exist: text, select and checkbox. The date type arrives with WooCommerce 11.2. Registration must happen on the woocommerce_init action or later, and version 11.0 warns when a field is registered too early.

Validation and conditional fields

Each field accepts a sanitization function and a validation function. Since WooCommerce 9.9, the required, hidden and validation properties can depend on other values, described in JSON Schema and evaluated in the browser as well as on the server. A VAT number field can thus appear only for a business address.

Moving PHP customizations

The hooks that survive, and the others

WooCommerce publishes a hook mapping table. Hooks that touch calculation, such as cart fees, total recalculation, shipping rates or address formats by country, work with the blocks. Hooks that output content at a precise spot on the classic page, before the form or after the order notes, do not exist in the block.

The woocommerce_checkout_order_processed hook does not fire for orders placed through the Store API: use woocommerce_store_api_checkout_order_processed instead. Editing core fields through the woocommerce_checkout_fields filter is not supported at all.

Slots, JavaScript filters and inner blocks

To output content, the block offers dedicated slots, all still marked experimental. To change a label, JavaScript filters exist, such as the one for the place order button. For the rest, a plugin can register its own inner block, or filter a block’s rendering on the server.

The hooks documentation claims the place order button text cannot be changed in code: that is inaccurate, the placeOrderButtonLabel JavaScript filter does it. The text can also be edited directly in the editor.

Migrating step by step

Prepare on a copy

Work on a staging copy, with a recent backup of production. List your payment methods, your checkout-related plugins and your custom code, and check each one on the marketplace or in its documentation.

Replace the shortcode

Open the Checkout page, replace the shortcode with the Checkout block, or transform the block that wraps the shortcode into blocks. Do the same for the Cart: both pages must move together. With a block theme, work in the matching Site Editor template.

The tool that creates missing pages, among the tools of the Status screen, does not convert an existing page: it only creates absent pages. Deleting the old pages to have them recreated changes their IDs and addresses, with consequences for menus and redirects.

Test what matters

Place a full order with each payment method, express payments included. Check the additional fields in the order, in the admin and in emails. Verify the purchase event in your analytics tools, then watch the conversion rate and failed orders in the weeks after the switch.

Customizing with block settings

Settings spread across inner blocks

The Checkout block itself has almost no settings. Everything sits in its inner blocks: numbered form steps, whether company, address line 2 and phone are hidden, optional or required, express payment button styles, delivery icons and costs, the required terms checkbox, or the return to cart link.

The coupon form is the only inner block you can remove from the order summary. The place order button text is edited directly in the editor. With a block theme, the checkout template deliberately shows a simplified header, with the logo and title.

What version 11.2 changes

WooCommerce 11.2 changes the layout: the sidebar becomes a fixed 360 pixels instead of 35%, and the two-column breakpoint moves from 700 to 920 pixels of container width. Custom CSS tuned to the old values may misalign. Check your checkout page on a copy after the update.

Rolling back to shortcodes

Transforming the block

The official rollback is simple. Open the Checkout page or template, select the Checkout block in list view, use the toolbar transform and pick Classic Shortcode, then save. Do the same for the Cart: WooCommerce recommends reverting both pages.

When an incompatible plugin is detected, the sidebar button does the same in one click, with undo available. WordPress revisions keep the page’s previous content anyway.

What a rollback does not undo

Going back to shortcodes does not switch off the Store API, as the December 2025 flaw showed. Business rules added for the blocks, on the Store API side, stay useful even with a classic checkout. And fields created with the Additional Checkout Fields API do not appear in the classic checkout.

Should you migrate now?

What blocks bring on their own

Some features only exist with the blocks: block-based local pickup, delayed account creation, which also requires a block theme, or the experimental save for later option in the cart. Other new features, such as address autocomplete, arrived in both checkouts.

What the numbers really say

WooCommerce announced conversion gains of about 20% in 2021, then a few points in 2024, and one of its product managers, James Kemp, mentioned 27% on X in February 2026, with no published method. In April 2026, plugin vendor Studio Wombat found that only 12% of the roughly 7,200 customer stores whose cart page it could analyze used the Cart block. These figures remain vendor claims: only a measurement on your own store settles the question.

For a new store, the blocks are the natural choice. For a heavily customized store, the migration is decided after the audit, plugin by plugin. If your checkout runs through a page builder, our comparison of Gutenberg vs page builders helps settle the underlying question.

Summary table

Topic	Shortcode checkout	Block checkout	What to check
Architecture	PHP templates and hooks	React and Store API	Custom code
Payment methods	All	Only integrated ones	Each gateway on staging
Added fields	PHP filters, plugins	Additional Checkout Fields API	Emails and admin
New features	Fixes, some new features	New features first	The store’s real needs
Store API	Active	Active	Updates, business rules
Rollback	Not applicable	One-click transform	Both pages together

Frequently asked questions

Will WooCommerce remove the shortcode checkout?

No date has been announced. WooCommerce has repeatedly promised to keep supporting it for existing stores, and still fixes it in the 11.x releases.

Do I need the WooCommerce Blocks plugin?

No. That plugin was permanently closed in February 2024. The Cart and Checkout blocks are part of WooCommerce.

Why does my payment method not appear in the Checkout block?

Because its plugin does not provide the integration the blocks need. Update it, check its compatibility on the marketplace, or go back to the classic checkout in the meantime.

Can I add a VAT number field without a plugin?

Yes, with a few lines of code and the Additional Checkout Fields API, in the contact or address location. A field editor plugin remains simpler if you do not want to write code.

Does the block checkout convert better?

WooCommerce says so, with figures that have varied and no published method. Measure on your own store, before and after the switch, rather than relying on an average.

Conclusion

The Cart and Checkout blocks are WooCommerce’s future, and new stores are already there. For an existing store, the migration is not automatic, which is just as well: it calls for an audit of payment methods, plugins and custom code, a full test run and a way back.

Keep the December 2025 lesson in mind too. The Store API answers on every store, whatever the checkout page. Keeping WooCommerce up to date and testing your rules against that interface protects you more than the choice between shortcodes and blocks.

Sources

LaFactory designs, builds and maintains WordPress and WooCommerce sites, and develops its own plugins. Talk to us about your WordPress project.

Francis Rozange

Former section editor at Libération, he runs LaFactory, an international web agency since 1996.