The checkout is the most important page on any store. It’s where revenue happens, so it’s also the page store owners are most nervous about changing. That nervousness is understandable when it comes to WooCommerce’s newer Cart and Checkout blocks.
For years, WooCommerce’s cart and checkout were built with shortcodes and PHP templates. Many customisations, from extra fields to layout changes, were built on that foundation. The block-based cart and checkout work differently. They’re built with modern JavaScript, offer a cleaner and faster experience and have been the default for new stores since WooCommerce 8.3.
If your store still uses the shortcode checkout, you’ll likely consider migrating at some point. Here’s what changes, what to check and how to migrate safely.
What the blocks offer
The block-based cart and checkout bring several improvements:
- A cleaner, more modern design with a focus on conversion.
- A smoother experience, with fewer page reloads when customers update quantities, shipping methods or payment options.
- Better express payments, with wallet buttons integrated into the checkout and cart.
- Easier visual editing in the block editor, adjusting layout and some content without code.
- Ongoing development focus. New checkout features are being built primarily for the blocks.
What changes for developers
This is where migrations need care. The block checkout doesn’t use the same PHP templates and hooks as the shortcode checkout. Specifically:
- Template overrides for cart and checkout templates in your theme don’t apply.
- Many classic checkout hooks don’t apply in the same way, such as hooks that output content at specific points in the checkout form or filters that modify checkout fields.
- Custom fields added with the old woocommerce_checkout_fields filter won’t appear automatically.
- JavaScript customisations that relied on the classic checkout’s markup and events won’t work.
Instead, the block checkout offers its own extensibility, including APIs for adding fields, slot and fill areas for inserting content and integration interfaces for payment methods and extensions. WooCommerce has added an Additional Checkout Fields API in recent versions to make adding custom fields simpler.
For stores with significant custom checkout code, migration is a development project, not a switch.
Step 1: Audit your current checkout
Before migrating, list everything about your current checkout:
- Payment gateways in use.
- Shipping methods and plugins, including live rates, local pickup and delivery date pickers.
- Extensions that modify checkout: custom fields, gift messages, order notes, terms and conditions, newsletter signups, upsells and VAT number fields.
- Theme customisations: template overrides, custom CSS and JavaScript.
- Custom code in plugins or functions.php using checkout hooks.
- Tracking and analytics events on checkout.
Step 2: Check extension compatibility
WooCommerce shows compatibility notices for extensions that haven’t declared support for the block checkout. Also check each extension’s documentation and changelog for block checkout support.
Key areas:
- Payment gateways: most major gateways support the blocks, but confirm yours does, including express payment buttons.
- Shipping extensions: especially those adding custom shipping interfaces.
- Checkout field extensions: many have been updated, some haven’t.
- Subscription, booking and membership extensions.
If a critical extension doesn’t support the blocks yet, you may need to wait, find an alternative or keep the shortcode checkout for now.
Step 3: Rebuild custom functionality
For custom code, plan how each feature will work in the block checkout:
- Custom fields: use the Additional Checkout Fields API where possible, which lets you register fields in PHP that appear in the block checkout and save to the order.
- Content inserted at specific points: use the block checkout’s extensibility areas, or add blocks in the editor.
- Validation logic: implement through the supported APIs.
- Styling: target block checkout markup with updated CSS, or use the editor’s design controls and theme.json.
Check WooCommerce’s developer documentation for the current APIs, because the block checkout’s extensibility has expanded steadily.
Step 4: Set up on staging
Never migrate directly on a live store.
- Create a staging copy of the store.
- Edit the cart and checkout pages, replacing the shortcodes with the Cart and Checkout blocks. WooCommerce often offers a button to switch to the blocks directly.
- Configure block settings: which fields are shown, whether company name and phone are required, address line two, terms and conditions and order notes.
- Add any blocks or content you need, like trust messages or delivery information.
- Rebuild custom functionality.
Step 5: Test thoroughly
Test every path a customer might take:
- Guest checkout and logged-in checkout.
- Every payment method, including express payments.
- Every shipping method, including local pickup.
- Coupons, including free shipping coupons.
- Different countries and tax scenarios.
- Required and optional custom fields.
- Failed payments and retries.
- Mobile devices.
- Order emails and admin order details, confirming custom field data is saved.
- Analytics and conversion tracking.
Compare orders placed through the block checkout with orders from the old checkout to make sure nothing is missing.
Step 6: Launch carefully
When you’re confident:
- Choose a quiet time to switch.
- Keep a backup and a clear rollback plan. Switching back to the shortcode checkout is as simple as replacing the blocks with the shortcodes again, as long as you haven’t removed old customisations.
- Place a real test order immediately after switching.
- Watch orders, error logs and customer feedback closely for the first days.
Express payments
The block checkout makes express payment options, like wallet buttons, more prominent. These can significantly speed up checkout, especially on mobile, because customers can pay with saved details in a couple of taps.
Check:
- Which express methods your gateway supports.
- That express payments work correctly with your shipping and tax setup.
- That custom required fields don’t conflict with express checkout flows.
Performance
The block checkout loads modern JavaScript. On most stores it feels faster to use, because updates happen without full page reloads. Keep checkout pages lean anyway: remove unnecessary third-party scripts, chat widgets and pop-ups from the checkout, and keep payment page script inventories tight for security.
Design and branding
The blocks can be styled through the editor and theme.json in block themes, or with CSS in classic themes. Common adjustments:
- Matching button colours and fonts to your brand.
- Adjusting spacing and layout.
- Adding trust messages, delivery information or support contact details near the place order button.
Keep the design clean. The blocks are designed for conversion; heavy customisation can undo that.
When to stay on the shortcode checkout for now
Staying on the shortcode checkout temporarily is reasonable when:
- Critical extensions don’t support the blocks yet.
- Your checkout relies on extensive custom code that would take significant effort to rebuild.
- You’re approaching a busy sales period and don’t want to risk changes.
Plan the migration for a calmer time, and keep an eye on extension updates. Over time, the block checkout will receive the most attention from WooCommerce development.
What I check first on a migration
When a client asks me to move their checkout to blocks, the first thing I look for is custom code using woocommerce_checkout_fields, woocommerce_after_order_notes and similar hooks. Each one represents a feature that needs rebuilding. Listing them up front turns a vague migration into a clear set of tasks with realistic estimates.
Measure before and after
Record your checkout conversion rate, average checkout time and payment method mix for a few weeks before migrating, then compare after. Real numbers tell you whether the new checkout is helping, and they make it easy to spot a problem quickly if one appears.
Keep the old code until you’re sure
Leave old checkout customisations disabled but available for a few weeks after switching. If you need to roll back, everything is ready, and you can remove the old code calmly once the new checkout has proven itself.
Frequently asked questions
Are the Cart and Checkout blocks required?
They’re the default for new stores, but existing stores can continue using the shortcode checkout. Migration is recommended over time for new features and long-term support.
Will my custom checkout fields work with the blocks?
Fields added through old PHP filters won’t appear automatically. Rebuild them with the block checkout’s APIs, such as the Additional Checkout Fields API, or use an extension that supports the blocks.
Can I switch back if something goes wrong?
Yes. Replace the blocks with the cart and checkout shortcodes on those pages. Keep your old customisations in place until you’re confident in the new checkout.
Do the blocks improve conversion rates?
They’re designed for a smoother, faster checkout with better express payment options, which often helps. Measure your own results before and after.
Final thoughts
The Cart and Checkout blocks are the future of WooCommerce checkout, with a cleaner experience and better express payments. Migrating safely means auditing your current setup, checking extension compatibility, rebuilding custom features with the new APIs, testing every path on staging and launching with a rollback plan. Take it step by step, and your checkout can become faster and more modern without risking the revenue that flows through it.




