Woocommerce Blocks

WooCommerce Blocks

Overview

WooCommerce Blocks replaces the classic shortcode-based cart and checkout with React-powered Gutenberg blocks. Custom plugins can extend the Checkout Block by registering inner blocks (custom fields inside checkout steps), using SlotFills (inject UI into predefined injection points), and extending the Store API to save and retrieve custom data. The block-based checkout is the default for new WooCommerce stores since version 8.3.

When to Use This Skill

• When adding custom fields to the checkout form (gift message, delivery date picker, VAT number)
• When injecting promotional content or upsell banners into the cart or checkout block
• When creating a custom checkout step with additional business logic
• When replacing the legacy shortcode checkout on existing WooCommerce sites
• When building a plugin that extends checkout behavior without modifying core templates

Core Instructions

1. Register a Checkout Inner Block

Inner blocks are React components that render inside a checkout step. They require PHP block registration + a JS/React frontend:

   <?php
   // my-checkout-fields/my-checkout-fields.php
   add_action('woocommerce_blocks_loaded', function () {
       if (!class_exists('Automattic\WooCommerce\Blocks\Integrations\IntegrationInterface')) {
           return;
       }
       require_once __DIR__ . '/class-my-checkout-integration.php';
       add_action(
           'woocommerce_blocks_checkout_block_registration',
           function ($integration_registry) {
               $integration_registry->register(new My_Checkout_Integration());
           }
       );
   });

   <?php
   // class-my-checkout-integration.php
   use Automattic\WooCommerce\Blocks\Integrations\IntegrationInterface;

   class My_Checkout_Integration implements IntegrationInterface {
       public function get_name() {
           return 'my-checkout-fields';
       }

       public function initialize() {
           $this->register_block_frontend_scripts();
           $this->register_inner_block();
       }

       private function register_block_frontend_scripts() {
           wp_register_script(
               'my-checkout-fields-frontend',
               plugin_dir_url(__FILE__) . 'build/frontend.js',
               ['wc-blocks-checkout', 'wp-element'],
               filemtime(plugin_dir_path(__FILE__) . 'build/frontend.js'),
               true
           );
       }

       private function register_inner_block() {
           register_block_type(plugin_dir_path(__FILE__) . 'build/blocks/gift-message/block.json');
       }

       public function get_script_handles() {
           return ['my-checkout-fields-frontend'];
       }

       public function get_editor_script_handles() {
           return [];
       }

       public function get_script_data() {
           return [];
       }
   }

2. Create the inner block React component

   // src/blocks/gift-message/index.js
   import { registerCheckoutBlock } from "@woocommerce/blocks-checkout";
   import { __ } from "@wordpress/i18n";
   import { useEffect, useState } from "@wordpress/element";
   import {
     useExtensionCartUpdateData,
     extensionCartUpdate,
   } from "@woocommerce/blocks-checkout";

   const Block = ({ children, checkoutExtensionData }) => {
     const [giftMessage, setGiftMessage] = useState("");

     // Persist gift message to cart extension data
     const handleChange = (e) => {
       const value = e.target.value;
       setGiftMessage(value);
       extensionCartUpdate({
         namespace: "my-checkout-fields",
         data: { gift_message: value },
       });
     };

     return (
       <div className="wc-block-checkout__gift-message">
         <label htmlFor="gift-message">
           {__("Gift message (optional)", "my-checkout-fields")}
         </label>
         <textarea
           id="gift-message"
           value={giftMessage}
           onChange={handleChange}
           placeholder={__("Write your message here...", "my-checkout-fields")}
           rows={3}
           maxLength={200}
         />
         <span className="character-count">{giftMessage.length}/200</span>
       </div>
     );
   };

   registerCheckoutBlock({
     metadata: {
       name: "my-checkout-fields/gift-message",
       title: "Gift Message",
       category: "woocommerce",
       parent: ["woocommerce/checkout-shipping-methods-block"],
       attributes: {},
     },
     component: Block,
   });

3. Extend the Store API to persist custom data

   <?php
   // Extend the Store API Cart schema to accept and store custom extension data
   add_action('woocommerce_blocks_loaded', function () {
       woocommerce_store_api_register_endpoint_data([
           'endpoint'        => Automattic\WooCommerce\StoreApi\Schemas\V1\CartSchema::IDENTIFIER,
           'namespace'       => 'my-checkout-fields',
           'schema_callback' => function () {
               return [
                   'gift_message' => [
                       'description' => 'Gift message for the order',
                       'type'        => 'string',
                       'context'     => ['view', 'edit'],
                       'readonly'    => false,
                       'sanitize_callback' => 'sanitize_textarea_field',
                   ],
               ];
           },
           'schema_type' => ARRAY_A,
       ]);

       // Save the gift message to WC session when cart is updated
       woocommerce_store_api_register_update_callback([
           'namespace' => 'my-checkout-fields',
           'callback'  => function (array $data) {
               if (isset($data['gift_message'])) {
                   WC()->session->set('gift_message', sanitize_textarea_field($data['gift_message']));
               }
           },
       ]);
   });

   // Transfer session data to order meta on checkout
   add_action('woocommerce_checkout_order_created', function ($order) {
       $gift_message = WC()->session->get('gift_message', '');
       if (!empty($gift_message)) {
           $order->update_meta_data('_gift_message', $gift_message);
           $order->save();
       }
   });

4. Use SlotFills for injecting UI without inner blocks

SlotFills are simpler than inner blocks — they inject content into predefined slots:

   // src/frontend.js
   import { registerPlugin } from "@wordpress/plugins";
   import { ExperimentalOrderMeta } from "@woocommerce/blocks-checkout";
   import { __ } from "@wordpress/i18n";
   import { useSelect } from "@wordpress/data";
   import { CART_STORE_KEY } from "@woocommerce/block-data";

   const CartUpsellBanner = () => {
     const cartTotal = useSelect((select) => {
       const cart = select(CART_STORE_KEY).getCartData();
       return cart?.totals?.total_items;
     });

     const freeShippingThreshold = 5000; // $50.00 in cents
     const remaining = freeShippingThreshold - parseInt(cartTotal ?? "0");

     if (remaining <= 0) return null;

     return (
       <div className="free-shipping-banner">
         {__(`Add $${(remaining / 100).toFixed(2)} more for free shipping!`, "my-checkout-fields")}
       </div>
     );
   };

   registerPlugin("my-cart-upsell", {
     render: () => (
       <ExperimentalOrderMeta>
         <CartUpsellBanner />
       </ExperimentalOrderMeta>
     ),
     scope: "woocommerce-checkout",
   });

5. Build and enqueue assets with `@wordpress/scripts`

   // package.json
   {
     "scripts": {
       "build": "wp-scripts build src/frontend.js src/blocks/gift-message/index.js",
       "start": "wp-scripts start src/frontend.js src/blocks/gift-message/index.js"
     },
     "devDependencies": {
       "@wordpress/scripts": "^30.0.0"
     }
   }

   // src/blocks/gift-message/block.json
   {
     "$schema": "https://schemas.wp.org/trunk/block.json",
     "apiVersion": 3,
     "name": "my-checkout-fields/gift-message",
     "title": "Gift Message",
     "category": "woocommerce",
     "parent": ["woocommerce/checkout-shipping-methods-block"],
     "textdomain": "my-checkout-fields",
     "editorScript": "file:../../build/blocks/gift-message/index.js",
     "script": "file:../../build/blocks/gift-message/index.js",
     "style": "file:../../build/blocks/gift-message/style-index.css"
   }

Examples

Checkout field validation

Validation of custom checkout data should be done server-side via the Store API update callback. Client-side filters (__experimentalRegisterCheckoutFilters) can only modify display values (e.g., price formatting), not validate form fields.

<?php
// Server-side validation in the Store API update callback
woocommerce_store_api_register_update_callback([
    'namespace' => 'my-checkout-fields',
    'callback'  => function (array $data) {
        if (isset($data['gift_message'])) {
            $message = sanitize_textarea_field($data['gift_message']);

            // Reject messages that contain URLs
            if (preg_match('#https?://#i', $message)) {
                throw new \Automattic\WooCommerce\StoreApi\Exceptions\RouteException(
                    'invalid_gift_message',
                    __('Gift messages cannot contain links.', 'my-checkout-fields'),
                    400
                );
            }

            WC()->session->set('gift_message', $message);
        }
    },
]);

On the client side, handle the error response from extensionCartUpdate to display validation messages:

import { extensionCartUpdate } from "@woocommerce/blocks-checkout";

const handleChange = async (e) => {
  const value = e.target.value;
  setGiftMessage(value);
  try {
    await extensionCartUpdate({
      namespace: "my-checkout-fields",
      data: { gift_message: value },
    });
    setError(null);
  } catch (err) {
    setError(err.message);
  }
};

Disable a payment method for certain cart conditions

<?php
// Hide "Pay Later" payment method if cart contains digital-only products
add_filter(
    'woocommerce_blocks_payment_method_type_registration',
    function ($payment_method_registry) {
        $payment_method_registry->register(
            new class implements \Automattic\WooCommerce\Blocks\Payments\PaymentMethodTypeInterface {
                public function is_active() { return true; }
                public function get_payment_method_script_handles() { return []; }
                public function get_payment_method_data() { return []; }
                public function get_name() { return 'custom-payment-guard'; }
                public function initialize() {}
            }
        );
        return $payment_method_registry;
    }
);

add_filter('__experimental_woocommerce_blocks_payment_gateway_features_list', function ($features, $name) {
    if ($name === 'pay-later') {
        // Check if all items in cart are virtual/downloadable
        $cart_has_physical = false;
        foreach (WC()->cart->get_cart() as $item) {
            $product = $item['data'];
            if (!$product->is_virtual() && !$product->is_downloadable()) {
                $cart_has_physical = true;
                break;
            }
        }
        if (!$cart_has_physical) {
            $features['available'] = false;
        }
    }
    return $features;
}, 10, 2);

Best Practices

• Use `extensionCartUpdate` instead of local state for data that must survive page reload — it stores data in the WooCommerce session via the Store API
• Sanitize all custom data server-side — PHP sanitize_textarea_field, sanitize_text_field, and absint are essential for any data written to order meta
• Build with `@wordpress/scripts` — it handles dependency extraction, webpack config, and asset versioning automatically for WordPress/Gutenberg projects
• Use `block.json` for inner blocks — the block registry requires a block.json manifest; it also enables automatic asset loading in the editor
• Test both classic and block checkout — some stores may still use the shortcode checkout; conditionally enqueue scripts only when block checkout is detected
• Use the `woocommerce_store_api_register_update_callback` for server validation — client-side validation can be bypassed; always re-validate extension data in the callback
• Prefix all meta keys and namespaces with your plugin slug to avoid conflicts with other plugins

Common Pitfalls

Related Skills

• @woocommerce-plugin-development
• @woocommerce-rest-api
• @gutenberg-block-development
• @checkout-flow-optimization
• @woocommerce-subscriptions

B2B VAT Number Field: Build Setup and Checkout Validation

Problem/Feature Description

A B2B supplies company sells to businesses across the EU and needs to collect VAT registration numbers at checkout for proper invoicing and VAT exemption processing. A developer has already built the server-side Store API registration and order meta storage for the VAT field. Now they need two things: (1) a proper build configuration so the JavaScript source can be compiled for WordPress, and (2) client-side validation that checks the VAT number format before the customer can complete the order.

The validation requirement is: VAT numbers must start with a 2-letter EU country code followed by 2–13 alphanumeric characters (e.g. "DE123456789", "GB999999973"). If the format is invalid, checkout should be blocked and the customer shown a helpful error message on the VAT field.

The plugin has two JavaScript entry points: src/frontend.js (SlotFill/general frontend) and src/blocks/vat-number/index.js (the inner block). Both must be built.

Output Specification

Produce the following files:

1. package.json — Node.js package file with the build scripts and correct devDependencies for a WordPress/WooCommerce blocks project 2. src/blocks/vat-number/block.json — Block manifest for the VAT number inner block (assume it should appear inside the checkout contact information step) 3. src/blocks/vat-number/validation.js — The client-side validation logic that hooks into WooCommerce checkout filters 4. BUILD_NOTES.md — Brief notes explaining: which build tool is used and why, how to run a development build vs production build, and what the entry points are

The VAT number block already exists — only the build setup and validation file need to be created. The grader will review these four files.

Delivery Date Picker for Block Checkout

Problem/Feature Description

A mid-size e-commerce store selling perishable food items has recently migrated to the WooCommerce block-based checkout. Their operations team needs customers to select a preferred delivery date during checkout so that the warehouse can schedule refrigerated shipments accordingly. Without this field, customers call in after placing orders to request specific dates, creating significant manual overhead.

The store's developer needs to create a WordPress plugin that adds a "Preferred Delivery Date" picker field inside the checkout shipping step. When a customer selects a date, it must be reliably recorded on the order so the warehouse management system can read it. The field should appear after the shipping method selection.

Output Specification

Produce the following files for a WordPress plugin called delivery-date-checkout:

1. delivery-date-checkout.php — Main plugin bootstrap file that hooks into WooCommerce Blocks loading 2. class-delivery-date-integration.php — The integration class that registers scripts and the inner block 3. src/blocks/delivery-date/index.js — The React inner block component 4. src/blocks/delivery-date/block.json — Block manifest file

The plugin should:

• Register the delivery date field as an inner block inside the checkout
• Persist the selected date value through the WooCommerce Store API so it survives page reloads
• Save the delivery date to the order on checkout completion
• Sanitize all incoming data before saving

Do NOT actually build/compile the JavaScript — just produce the source files. Include a brief NOTES.md explaining the Store API registration flow.

Dynamic Free Shipping Progress Banner for Block Checkout

Problem/Feature Description

An online fashion retailer wants to increase their average order value by showing customers how close they are to earning free shipping during checkout. Their UX team has found that displaying a real-time "Add $X more for free shipping!" message significantly reduces cart abandonment and encourages customers to add one more item before completing their order.

The store runs WooCommerce with the block-based cart and checkout. The development team needs a lightweight JavaScript plugin — no inner block required — that injects a banner into the checkout order summary area. The banner should read the current cart total dynamically and display the remaining amount needed to reach the free shipping threshold of $75.00. Once the threshold is met, the banner should disappear.

The solution must work within the WooCommerce block checkout ecosystem and not require modifying any WooCommerce core templates or PHP files (a pure JavaScript approach is preferred).

Output Specification

Produce the following files:

1. src/frontend.js — The JavaScript/React SlotFill plugin that injects the banner 2. plugin-loader.php — Minimal PHP file that enqueues the compiled frontend script 3. ARCHITECTURE.md — A short document (bullet points are fine) explaining which WooCommerce slot/API was used to inject the banner, why that approach was chosen over an inner block, and how the cart total is read

The banner logic and data-fetching approach are the focus — the grader will review the source files directly, so no build step is needed.