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.