WooCommerce Blocks Development
Before writing code
Fetch live docs:
- Web-search
site:developer.woocommerce.com blocks extensibility for blocks extension docs
- Fetch
https://developer.wordpress.org/block-editor/ for Block Editor handbook
- Web-search
woocommerce checkout blocks extension api for checkout extension patterns
Architecture Overview
What WooCommerce Blocks Are
React-based blocks for the WordPress block editor (Gutenberg):
- Cart Block — replaces
[woocommerce_cart] shortcode
- Checkout Block — replaces
[woocommerce_checkout] shortcode (default since WC 8.3)
- Product Blocks — grids, filters, search, featured products
- Mini Cart Block — header cart widget
Store API
A dedicated REST API powering the block-based cart and checkout:
- Base:
/wp-json/wc/store/v1/
- Endpoints:
cart, cart/items, checkout, products, batch
- Nonce-authenticated (no API keys needed — runs in the customer's session)
- Separate from the WooCommerce REST API v3 (which is admin-facing)
Key Packages
| Package |
Purpose |
@woocommerce/blocks-checkout |
Checkout extension API |
@woocommerce/blocks-registry |
Block type registration |
@woocommerce/blocks-components |
Shared React components |
@woocommerce/settings |
Access WC settings in JS |
@wordpress/blocks |
Core block registration |
@wordpress/block-editor |
Editor components |
@wordpress/element |
React wrapper |
Extending Checkout Blocks
Integration Points
The block-based checkout provides extension points:
- Inner Blocks — add custom blocks within checkout layout
- Slot Fills — inject content into predefined areas (before/after payment, shipping, etc.)
- Filters — modify text, labels, and data displayed in checkout
- Store API extensions — add custom data to cart/checkout API responses
Checkout Extension API (PHP Side)
Use ExtendSchema and StoreApi classes to:
- Extend the Store API response with custom data
- Add custom endpoint data to cart items, shipping, or checkout
- Process custom data during checkout via
ExtendSchema::register_endpoint_data()
Checkout Extension API (JS Side)
Use @woocommerce/blocks-checkout exports:
registerCheckoutFilters — modify displayed values (item names, prices, subtotals)
ExperimentalOrderMeta — slot for adding custom order meta display
ExperimentalDiscountsMeta — slot for custom discount display
Registering a Checkout Block
- Register the block server-side with
register_block_type()
- Declare the block as a checkout inner block via
BlockRegistry
- Provide
edit and save React components
- Enqueue scripts for the frontend and editor
Building Custom Product Blocks
Block Registration
Register with register_block_type():
block.json — metadata file defining name, attributes, supports, editor/frontend scripts
edit.js — editor component
save.js — save component (or null for dynamic)
render.php — server-side rendering for dynamic blocks
Server-Side Rendering
Use dynamic blocks with render_callback or render.php for product data:
- Access WooCommerce data via PHP (products, cart, etc.)
- Return HTML string from the render function
- Preferred for data-dependent blocks
Store API Extension
Adding Custom Data to Cart/Checkout
Register custom data via woocommerce_blocks_loaded action:
- Use
Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema
- Define namespace, schema, and data callback
- Data appears in Store API responses under
extensions.{namespace}
Processing Custom Checkout Data
Register checkout_data processing via woocommerce_store_api_checkout_update_order_from_request:
- Receives the order and the full checkout request
- Save custom data to order meta
Declaring Block Compatibility
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
);
}
});
Best Practices
- Declare
cart_checkout_blocks compatibility in every extension
- Use the Store API (not REST API v3) for frontend/cart/checkout interactions
- Use
@woocommerce/blocks-checkout hooks rather than DOM manipulation
- Enqueue block scripts only when the block is present on the page
- Follow Gutenberg coding standards for block development
- Test with both classic and block-based checkout
- Use
block.json for block metadata (WordPress standard)
Fetch the WooCommerce Blocks extension docs and Block Editor handbook for exact API methods, slot names, and filter signatures before implementing.
1---2name: woo-blocks3description: Build WooCommerce Blocks — Gutenberg block integration, block-based cart/checkout extensions, Store API, and the @woocommerce/blocks-checkout package. Use when extending the block editor for WooCommerce or customizing block-based checkout/cart.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/woo-blocks7---89# WooCommerce Blocks Development1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.woocommerce.com blocks extensibility` for blocks extension docs152. Fetch `https://developer.wordpress.org/block-editor/` for Block Editor handbook163. Web-search `woocommerce checkout blocks extension api` for checkout extension patterns1718## Architecture Overview1920### What WooCommerce Blocks Are2122React-based blocks for the WordPress block editor (Gutenberg):23- **Cart Block** — replaces `[woocommerce_cart]` shortcode24- **Checkout Block** — replaces `[woocommerce_checkout]` shortcode (default since WC 8.3)25- **Product Blocks** — grids, filters, search, featured products26- **Mini Cart Block** — header cart widget2728### Store API2930A dedicated REST API powering the block-based cart and checkout:31- Base: `/wp-json/wc/store/v1/`32- Endpoints: `cart`, `cart/items`, `checkout`, `products`, `batch`33- Nonce-authenticated (no API keys needed — runs in the customer's session)34- Separate from the WooCommerce REST API v3 (which is admin-facing)3536### Key Packages3738| Package | Purpose |39|---------|---------|40| `@woocommerce/blocks-checkout` | Checkout extension API |41| `@woocommerce/blocks-registry` | Block type registration |42| `@woocommerce/blocks-components` | Shared React components |43| `@woocommerce/settings` | Access WC settings in JS |44| `@wordpress/blocks` | Core block registration |45| `@wordpress/block-editor` | Editor components |46| `@wordpress/element` | React wrapper |4748## Extending Checkout Blocks4950### Integration Points5152The block-based checkout provides extension points:53- **Inner Blocks** — add custom blocks within checkout layout54- **Slot Fills** — inject content into predefined areas (before/after payment, shipping, etc.)55- **Filters** — modify text, labels, and data displayed in checkout56- **Store API extensions** — add custom data to cart/checkout API responses5758### Checkout Extension API (PHP Side)5960Use `ExtendSchema` and `StoreApi` classes to:611. Extend the Store API response with custom data622. Add custom endpoint data to cart items, shipping, or checkout633. Process custom data during checkout via `ExtendSchema::register_endpoint_data()`6465### Checkout Extension API (JS Side)6667Use `@woocommerce/blocks-checkout` exports:68- `registerCheckoutFilters` — modify displayed values (item names, prices, subtotals)69- `ExperimentalOrderMeta` — slot for adding custom order meta display70- `ExperimentalDiscountsMeta` — slot for custom discount display7172### Registering a Checkout Block73741. Register the block server-side with `register_block_type()`752. Declare the block as a checkout inner block via `BlockRegistry`763. Provide `edit` and `save` React components774. Enqueue scripts for the frontend and editor7879## Building Custom Product Blocks8081### Block Registration8283Register with `register_block_type()`:84- `block.json` — metadata file defining name, attributes, supports, editor/frontend scripts85- `edit.js` — editor component86- `save.js` — save component (or `null` for dynamic)87- `render.php` — server-side rendering for dynamic blocks8889### Server-Side Rendering9091Use dynamic blocks with `render_callback` or `render.php` for product data:92- Access WooCommerce data via PHP (products, cart, etc.)93- Return HTML string from the render function94- Preferred for data-dependent blocks9596## Store API Extension9798### Adding Custom Data to Cart/Checkout99100Register custom data via `woocommerce_blocks_loaded` action:101- Use `Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema`102- Define namespace, schema, and data callback103- Data appears in Store API responses under `extensions.{namespace}`104105### Processing Custom Checkout Data106107Register `checkout_data` processing via `woocommerce_store_api_checkout_update_order_from_request`:108- Receives the order and the full checkout request109- Save custom data to order meta110111## Declaring Block Compatibility112113```php114add_action( 'before_woocommerce_init', function() {115 if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {116 \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(117 'cart_checkout_blocks', __FILE__, true118 );119 }120});121```122123## Best Practices124125- Declare `cart_checkout_blocks` compatibility in every extension126- Use the Store API (not REST API v3) for frontend/cart/checkout interactions127- Use `@woocommerce/blocks-checkout` hooks rather than DOM manipulation128- Enqueue block scripts only when the block is present on the page129- Follow Gutenberg coding standards for block development130- Test with both classic and block-based checkout131- Use `block.json` for block metadata (WordPress standard)132133Fetch the WooCommerce Blocks extension docs and Block Editor handbook for exact API methods, slot names, and filter signatures before implementing.