Working With WooCommerce Product Blocks
Product blocks are not a nicer wrapper around the old shortcodes. They query differently, render differently and extend differently, and that last difference is what catches stores out at checkout.
Two different things are called product blocks, and confusing them wastes a lot of time. One is the set of blocks you place on pages and templates to display products. The other is a block-based editor for product data in the admin, replacing the tabbed panel that has existed since the beginning. They arrived separately, they are governed separately, and only one of them affects what visitors see.
The front-end blocks
The blocks worth knowing are fewer than the inserter suggests, because several older ones have been folded into one.
- Product Collection is the workhorse. It runs a product query with the filtering, sorting and layout options exposed in the sidebar, and in a block theme it can inherit the query from the template it sits in — which is what makes one template serve every category archive correctly.
- Single Product embeds one product with its price and add-to-cart control, useful on landing pages.
- Featured Product and Featured Category are presentation blocks with a background image and a call to action.
- Filter blocks provide layered navigation next to a product listing, covered in more depth under product filtering.
- Cart and Checkout are not display blocks at all. They are full replacements for the classic pages.
Older stores may still have blocks from earlier generations of this feature sitting in saved content. They generally keep working, but new work should use Product Collection, because that is where query and performance improvements land.
If you are new to the editor's vocabulary, what a block is in WordPress is the shorter prerequisite; if your theme is a block theme, the product templates are edited in the Site Editor alongside everything else, which is the model described in WordPress block themes.
Blocks or shortcodes
| Situation | Use |
|---|---|
| Editing a page in the block editor | Blocks |
| Inside a page builder's text widget | Shortcode |
| Generated in a template file or a snippet | Shortcode, or the underlying function |
| Needing the query to follow the current archive | Product Collection |
| Content authored by someone non-technical | Blocks |
| Cart and checkout on a store built this year | Blocks |
| Cart and checkout with older extensions | Test before switching |
The product shortcodes are not deprecated and remain the pragmatic answer in several of those rows. Choosing blocks everywhere on principle is not a strategy.
The checkout question, which is the important one
The block cart and checkout are a rewrite, not a restyle. They render client-side from data supplied by WooCommerce's Store API, rather than by running the sequence of template actions the classic checkout runs. Everything follows from that:
- An extension that adds a field, a notice or a payment option by hooking a classic checkout action will render nothing, silently.
- Payment gateways need explicit block support, which most maintained ones now have and abandoned ones never will.
- Custom checkout code you wrote yourself has to be rewritten against the block integration layer.
This is not a bug and it is not going away. The correct procedure is to switch on staging, place a real order with every gateway and every extension enabled, and check the order that results — not to switch on production and watch. If fields or gateways disappear after the change, that is the cause, and it is a different problem from the general failures covered in checkout not working.
The product block editor in the admin
The second meaning. WooCommerce has been building a block-based product editing screen to replace the classic product data metabox, and it has been rolling out gradually, opt-in, and not for every product type at once. Two practical consequences:
- Check your own installation rather than following a guide. Whether it is available, and whether it is the default, depends on your version and on the features screen in WooCommerce's advanced settings.
- Extensions add fields to the classic panel. A plugin that adds a tab or a field to product data may not have an equivalent in the block editor yet, so switching can hide settings that still exist in the database. Switch back if a field you rely on disappears; the data is not lost.
If you administer a store with several product data extensions, there is no urgency here. The classic panel remains functional.
A sensible position
Use Product Collection for new front-end listings and keep shortcodes where they are already working. Treat the cart and checkout blocks as a migration with a test plan rather than a setting to toggle. Leave the admin product editor alone until every extension you depend on supports it, and revisit that decision when you next audit plugins rather than on an announcement. Blocks are the direction of travel, but the cost of moving early is paid entirely at checkout, which is the one place a store cannot afford surprises.
Frequently asked
- The product listing shortcodes still work and remain the sensible choice inside page builders, template files and anywhere content is generated programmatically. What has genuinely moved on is cart and checkout, where the block versions are the ones receiving new capability.
- It is a block-based replacement for the classic product data panel in the admin, distinct from the product blocks you place on the front end. It has been introduced gradually behind a feature toggle, so check the features screen on your own installation rather than trusting a tutorial's screenshots.
- Because it hooks into the classic checkout template's actions, which the block checkout does not run. Block checkout extensions register through WooCommerce's Store API and block integration layer, so the extension needs a version that supports it.