WooCommerce Checkout Customization
Before writing code
Fetch live docs:
- Web-search
site:developer.woocommerce.com checkout for checkout documentation
- Web-search
woocommerce checkout blocks extensibility api for block checkout patterns
- 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:
- Register endpoint data with
ExtendSchema::register_endpoint_data()
- 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
- Validate fields (
woocommerce_checkout_process)
- Create order (
woocommerce_checkout_create_order)
- Process payment (
WC_Payment_Gateway::process_payment())
- On success: redirect to thank-you page
- 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.
1---2name: woo-checkout3description: 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.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/woo-checkout7---89# WooCommerce Checkout Customization1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.woocommerce.com checkout` for checkout documentation152. Web-search `woocommerce checkout blocks extensibility api` for block checkout patterns163. Web-search `woocommerce classic checkout customization hooks` for classic checkout hooks1718## Two Checkout Implementations1920### Classic Checkout (Shortcode-Based)2122- Uses `[woocommerce_checkout]` shortcode23- PHP-rendered with `WC_Checkout` class24- Fully extensible via actions and filters25- Template: `checkout/form-checkout.php`2627### Block-Based Checkout (Default Since WC 8.3)2829- Uses the Checkout Block in the block editor30- React-rendered on the frontend31- Extended via the Store API and `@woocommerce/blocks-checkout` package32- More structured extension API but different from classic hooks3334## Classic Checkout Customization3536### Checkout Fields3738Filter `woocommerce_checkout_fields` to modify fields:39- Field groups: `billing`, `shipping`, `account`, `order`40- Each field has: `type`, `label`, `placeholder`, `required`, `class`, `priority`, `validate`41- Field types: `text`, `textarea`, `select`, `radio`, `checkbox`, `email`, `tel`, `password`, `country`, `state`4243### Adding Custom Fields4445Add to the fields array in the `woocommerce_checkout_fields` filter:46- Set `priority` to control ordering47- Set `custom_attributes` for HTML attributes4849### Validating Custom Fields5051Action `woocommerce_checkout_process`:52- Check `$_POST` values53- Add errors with `wc_add_notice( $message, 'error' )`5455### Saving Custom Field Data5657Action `woocommerce_checkout_update_order_meta` (legacy) or `woocommerce_checkout_order_processed`:58- Save to order meta: `$order->update_meta_data( '_my_field', $value ); $order->save();`5960### Displaying Custom Fields6162- Admin: `woocommerce_admin_order_data_after_billing_address` action63- Emails: `woocommerce_email_after_order_table` action64- Thank-you page: `woocommerce_thankyou` action6566## Block Checkout Customization6768### Extending via Store API6970Add custom data to checkout process:711. Register endpoint data with `ExtendSchema::register_endpoint_data()`722. Process during checkout via `woocommerce_store_api_checkout_update_order_from_request`7374### Checkout Filters (JS)7576`registerCheckoutFilters` from `@woocommerce/blocks-checkout`:77- `itemName` — modify cart item name78- `cartItemPrice` — modify displayed price79- `subtotalPriceFormat` — modify subtotal format80- `coupons` — modify coupon display81- Custom filters via `__experimental_woocommerce_blocks_checkout_update_shipping_address`8283### Slot Fills (JS)8485Inject React components at predefined points:86- `ExperimentalOrderMeta` — after order summary87- `ExperimentalDiscountsMeta` — after discounts88- `ExperimentalOrderShippingPackages` — shipping packages area8990### Inner Blocks9192Register custom blocks as checkout inner blocks for maximum layout control.9394## Checkout Flow9596### Order Processing Sequence97981. Validate fields (`woocommerce_checkout_process`)992. Create order (`woocommerce_checkout_create_order`)1003. Process payment (`WC_Payment_Gateway::process_payment()`)1014. On success: redirect to thank-you page1025. Hooks: `woocommerce_checkout_order_processed`, `woocommerce_payment_complete`, `woocommerce_thankyou`103104### Cart to Order Conversion105106`WC_Checkout::create_order()`:107- Creates `WC_Order` from cart data108- Copies billing/shipping addresses, line items, fees, coupons109- Applies `woocommerce_checkout_create_order` filter110111## Checkout Fees112113Add fees via `woocommerce_cart_calculate_fees` action:114- `WC()->cart->add_fee( $name, $amount, $taxable, $tax_class )`115- Negative amounts for discounts116117## Best Practices118119- Support both classic and block checkout — test with both120- Use CRUD methods to save order data (HPOS compatible)121- Validate on the server side — never trust client-side validation122- Sanitize all checkout field input123- Use nonces for classic checkout forms124- Add clear error messages with `wc_add_notice()`125- Declare `cart_checkout_blocks` compatibility126127Fetch the WooCommerce checkout documentation for exact hook names, Store API extension methods, and block checkout patterns before implementing.