WooCommerce · Guide
How to Customize the WooCommerce Checkout
Short answer
WooCommerce has two checkouts: the Checkout block, default for new stores since version 8.3 in November 2023, and the classic shortcode checkout. Add fields to the block with the Additional Checkout Fields API on woocommerce_init, and change classic fields with the woocommerce_checkout_fields filter, then place a test order to confirm the value saves.
Key takeaways
- New stores use the Cart and Checkout blocks by default since WooCommerce 8.3, released in November 2023.
- The Additional Checkout Fields API needs WooCommerce 8.9.0 or newer and registers fields on woocommerce_init.
- Block checkout fields go in three locations: contact, address, or order, with four types: text, select, checkbox, and date.
- Classic checkout fields use the woocommerce_checkout_fields filter, which does nothing on the block checkout.
- Address field values save under _wc_billing/ and _wc_shipping/ keys, while contact and order values save under _wc_other/.
Which checkout does your store use?
WooCommerce has two checkouts, and the way you customize each one is different, so check which one your store runs before you change anything.
For stores started after the release of version 8.3 in November 2023, the Cart and Checkout blocks are the default experience, according to the WooCommerce customization guide.
To check, open Pages, edit the page called Checkout, and look at what is on it. A Checkout block means block checkout, while the text [woocommerce_checkout] means classic checkout.
Existing stores were not switched when they upgraded to 8.3, so an older store keeps the checkout it already had until someone changes it by hand.
Our guide on Checkout blocks vs the classic shortcode compares the two in detail if you want the full picture.
What can you change without code?
You can change the checkout page, the terms page, and the layout of the Checkout block in the editor, with no code at all.
WooCommerce.com says that with a block theme you can customize the Cart and Checkout templates to fit your needs, and no customization is required for the block cart and checkout to function, in the customization guide.
Open the Checkout page in the editor to move, hide, or restyle its inner blocks, such as Contact information, Shipping address, and Payment options.
You can also hide optional core fields, such as the company field, from the Checkout block sidebar in the editor, without writing code.
What you cannot do without code is add a brand-new field to the block checkout. That needs the Additional Checkout Fields API, covered below.
How do you set the checkout page and its endpoints?
Assign the checkout page under WooCommerce > Settings > Advanced > Page setup, and leave the checkout endpoints alone unless you have a clear reason to change them.
WooCommerce.com says the Advanced settings area is where you configure store pages such as the cart and checkout, at WooCommerce > Settings > Advanced, in the Advanced settings documentation.
The page assignments include the Cart page, the Checkout page, the My account page, and the Terms and conditions page. Pick the right page in each dropdown and save.
The checkout endpoints are Pay, Order received, Add payment method, Delete payment method, and Set default payment method, according to the same page. They should be unique and generally do not need changing.
When you use the classic checkout, the terms and conditions appear inline and the customer ticks a box. On the block checkout, shoppers see a line that reads "By proceeding with your purchase you agree to our Terms and Conditions and Privacy Policy."
Read the WooCommerce settings explained for the rest of the settings screens before you change anything else.
How do you add a field to the Checkout block?
Register the field with the Additional Checkout Fields API, which needs WooCommerce 8.9.0 or newer and places the field in the contact, address, or order section.
The WooCommerce developer guide says this feature requires a minimum version of WooCommerce 8.9.0, and that you register fields with woocommerce_register_additional_checkout_field().
Call that function on the woocommerce_init action or later, since registering earlier can cause setup and translation problems, according to the Additional checkout fields documentation.
Give each field an ID in namespace/field-name form, a label, a location, and a type. The four supported types are text, select, checkbox, and date.
| Location | Where the field appears | Good for |
|---|---|---|
contact | With the email address at the top | A marketing opt-in checkbox |
address | In the shipping and billing address forms | A delivery note or tax ID |
order | In the order information section | A gift message or a source question |
Put the code in a small custom plugin, not in your theme, so the field survives a theme change. A code snippet plugin works too.
How do you add or change a field on the classic checkout?
On the classic checkout, change the field list with the woocommerce_checkout_fields filter, which the block checkout does not run.
The classic checkout runs through PHP templates, while the Checkout block is built in the browser, so the old filter cannot touch the block, as the Advanced Custom Fields guide explains.
With the filter you can add a field, remove one such as the company field, change a label or placeholder, or mark a field required. Each field has a type, a label, and a priority that sets its order.
The classic checkout page must hold the [woocommerce_checkout] shortcode and be assigned as the checkout page under WooCommerce > Settings > Advanced, as the Advanced settings documentation explains.
If your checkout is the block version, switching the page back to the classic shortcode brings the old filter back to life, but you lose the block layout.
How do you validate and read the new field values?
Add validation with a validate_callback on the field, and read saved values with the CheckoutFields helper instead of guessing the meta key.
The Additional checkout fields documentation says you can add custom validation and sanitization with WordPress action hooks, including a validate_callback that runs after sanitization.
Conditional visibility, which shows a field only when a rule matches, needs WooCommerce 9.9.0 or newer, according to the conditional fields guide.
Values are saved to meta keys with set prefixes: _wc_billing/ and _wc_shipping/ for address fields, and _wc_other/ for contact and order fields, according to the same documentation.
Use the get_field_from_object helper to read a value from an order or a customer. The docs recommend the helper over raw meta keys, since it handles future changes.
Date fields store values as strings in YYYY-MM-DD format, and they support min and max options to limit the dates a shopper can pick.
Contact fields are saved to the shopper's account and show in the Account details section, while address fields are saved to both the customer and the order, according to the Additional checkout fields documentation.
How do you check your changes worked?
Place a test order with the new field filled in, then open the order in the dashboard and confirm the value saved and shows where you expect.
First, check the field appears on the checkout page in a private browser window, with an item in the cart. Fill it in and place the order.
Open WooCommerce > Orders, open the new order, and look for the field value in the order details. The docs say values also appear on the admin order screen, the thank-you page, and order emails.
If the field is missing, confirm which checkout you run. Fields added with the old woocommerce_checkout_fields filter never appear on the block checkout.
If the checkout itself breaks after a change, read how to fix WooCommerce checkout not working before you undo the whole edit.
If the page shows a blank screen instead of an error, turn on logging as the debugging handbook explains, then reload the page and read the log.
What mistakes should you avoid?
The most common mistake is adding a field with the classic filter and wondering why nothing shows on the block checkout.
- Do not make a field required unless you must. A required field that cannot be filled in blocks every order.
- Do not add fields the order does not need. Each extra field adds friction at the step where shoppers are closest to paying.
- Do not put checkout code in a parent theme. A theme update wipes it, so use a small plugin instead.
- Do not skip the test order. A field that shows but never saves is worse than no field at all.
If checkout feels slow rather than broken, read how to speed up the WooCommerce checkout.
Taxes can also add fields and totals at checkout, so check how to set up taxes in WooCommerce before you add more fields.
How do express payment methods handle custom fields?
Express payment buttons, such as Apple Pay or Google Pay, collect the field values from the checkout page, so fields registered with the API still work there.
WooCommerce.com says fields registered with woocommerce_register_additional_checkout_field appear on the blocks checkout page, and when a shopper pays with an express method from that page, express checkout collects the values and saves them to the order, in the express checkouts documentation.
The same page warns that these fields are not shown on product or cart pages. If a required field is empty when an express payment starts there, WooCommerce refuses the payment and reports that the field is required.
A refused express payment is written to the logs, which you can read under WooCommerce > Status > Logs in the most recent gateway log, according to the same page.
Frequently asked questions
How do I tell which checkout my store uses?
Open Pages, edit the Checkout page, and look at its content. A Checkout block means block checkout, while the text [woocommerce_checkout] means classic checkout. You can also check which page is assigned under WooCommerce > Settings > Advanced > Page setup.
Can I use the Additional Checkout Fields API on an old WooCommerce version?
No. The Additional Checkout Fields API needs WooCommerce 8.9.0 or newer, according to the WooCommerce developer guide. Update WooCommerce first, and test the update on staging, since older versions do not have the registration function.
What field types can I add to the block checkout?
Yes. The API supports text, select, checkbox, and date fields, and date values are stored as strings in YYYY-MM-DD format. Date fields also support min and max options to limit the dates a shopper can pick.
Can I remove the company field from checkout?
Yes, but only with the right method for your checkout. On the classic checkout, use the woocommerce_checkout_fields filter to unset the company field. On the block checkout, hide it from the Checkout block settings sidebar in the editor.
Why does my custom field not show on the block checkout?
Fields added with the classic woocommerce_checkout_fields filter never appear on the block checkout, because the block builds its form from the Store API rather than a PHP template. Register the field with woocommerce_register_additional_checkout_field instead, or switch the page back to the classic shortcode.
Sources
- Additional checkout fields WooCommerce Developer Docs
- How to Add Additional Fields to the WooCommerce Checkout Block WooCommerce Developer Docs
- Customizing the Cart and Checkout Pages WooCommerce
- Advanced Settings WooCommerce
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
