woo-checkout

name	woo-checkout
description	Customize WooCommerce checkout — classic and block-based checkout, custom fields, validation, order processing, and checkout extensibility. Use when modifying the checkout flow, adding custom checkout fields, or integrating checkout extensions.

WooCommerce Checkout Customization

Before writing code

Fetch live docs:

1. Web-search site:developer.woocommerce.com checkout for checkout documentation
2. Web-search woocommerce checkout blocks extensibility api for block checkout patterns
3. Web-search woocommerce classic checkout customization hooks for classic checkout hooks

Two Checkout Implementations

Classic Checkout (Shortcode-Based)

• Uses [woocommerce_checkout] shortcode
• PHP-rendered with WC_Checkout class
• Fully extensible via actions and filters
• Template: checkout/form-checkout.php

Block-Based Checkout (Default Since WC 8.3)

• Uses the Checkout Block in the block editor
• React-rendered on the frontend
• Extended via the Store API and @woocommerce/blocks-checkout package
• More structured extension API but different from classic hooks

Classic Checkout Customization

Checkout Fields

Filter woocommerce_checkout_fields to modify fields:

• Field groups: billing, shipping, account, order
• Each field has: type, label, placeholder, required, class, priority, validate
• Field types: text, textarea, select, radio, checkbox, email, tel, password, country, state

Adding Custom Fields

Add to the fields array in the woocommerce_checkout_fields filter:

• Set priority to control ordering
• Set custom_attributes for HTML attributes

Validating Custom Fields

Action woocommerce_checkout_process:

• Check $_POST values
• Add errors with wc_add_notice( $message, 'error' )

Saving Custom Field Data

Action woocommerce_checkout_update_order_meta (legacy) or woocommerce_checkout_order_processed:

• Save to order meta: $order->update_meta_data( '_my_field', $value ); $order->save();

Displaying Custom Fields

• Admin: woocommerce_admin_order_data_after_billing_address action
• Emails: woocommerce_email_after_order_table action
• Thank-you page: woocommerce_thankyou action

Block Checkout Customization

Extending via Store API

Add custom data to checkout process:

1. Register endpoint data with ExtendSchema::register_endpoint_data()
2. Process during checkout via woocommerce_store_api_checkout_update_order_from_request

Checkout Filters (JS)

registerCheckoutFilters from @woocommerce/blocks-checkout:

• itemName — modify cart item name
• cartItemPrice — modify displayed price
• subtotalPriceFormat — modify subtotal format
• coupons — modify coupon display
• Custom filters via __experimental_woocommerce_blocks_checkout_update_shipping_address

Slot Fills (JS)

Inject React components at predefined points:

• ExperimentalOrderMeta — after order summary
• ExperimentalDiscountsMeta — after discounts
• ExperimentalOrderShippingPackages — shipping packages area

Inner Blocks

Register custom blocks as checkout inner blocks for maximum layout control.

Checkout Flow

Order Processing Sequence

1. Validate fields (woocommerce_checkout_process)
2. Create order (woocommerce_checkout_create_order)
3. Process payment (WC_Payment_Gateway::process_payment())
4. On success: redirect to thank-you page
5. Hooks: woocommerce_checkout_order_processed, woocommerce_payment_complete, woocommerce_thankyou

Cart to Order Conversion

WC_Checkout::create_order():

• Creates WC_Order from cart data
• Copies billing/shipping addresses, line items, fees, coupons
• Applies woocommerce_checkout_create_order filter

Checkout Fees

Add fees via woocommerce_cart_calculate_fees action:

• WC()->cart->add_fee( $name, $amount, $taxable, $tax_class )
• Negative amounts for discounts

Best Practices

• Support both classic and block checkout — test with both
• Use CRUD methods to save order data (HPOS compatible)
• Validate on the server side — never trust client-side validation
• Sanitize all checkout field input
• Use nonces for classic checkout forms
• Add clear error messages with wc_add_notice()
• Declare cart_checkout_blocks compatibility

Fetch the WooCommerce checkout documentation for exact hook names, Store API extension methods, and block checkout patterns before implementing.