A shop asks for a gift message at checkout. The field looks fine in a screenshot, but the packing team never sees the message. Or a developer pastes an older PHP snippet into a new store and nothing appears at all.
Both problems start with treating a checkout field as a box on a page. It is also a piece of order data, with rules about where it belongs, how it is checked, and who needs it next. Here is a practical way to add custom fields to WooCommerce’s Checkout Block without losing sight of the actual order workflow.
First, check which checkout your store uses
Open the assigned checkout page in the WordPress editor and inspect its block list. A Checkout block and a page using the classic [woocommerce_checkout] shortcode need different extension approaches. Check the live page too: a checkout plugin may replace what you expect to be there.
WooCommerce’s hook compatibility reference explains that many classic checkout display hooks do not run in the blocks. For new block checkout fields, use the Additional Checkout Fields API. Do not assume an older woocommerce_checkout_fields example will transfer unchanged.
Before changing code, write down the active WooCommerce version, checkout type, payment extensions and any existing field editor plugin. That small inventory helps explain why the same snippet behaves differently on two stores.
Decide whether the answer belongs to this order or the customer
The API offers three locations. Contact fields relate to the shopper’s account. Address fields appear in both billing and shipping forms and can hold separate values. Order fields belong to the purchase and do not prefill the next order. WooCommerce describes the storage behaviour in its additional checkout fields reference.
- A gift message usually belongs in order. A returning customer should not accidentally send last month’s birthday message again.
- A building detail that applies to a saved address may belong in address. Remember that it will also appear for billing; check whether that makes sense.
- A persistent customer preference may belong in contact. Decide whether it really needs to be asked during purchase.
For this example, use a short optional gift message stored against the order. Agree a useful limit with the packing team, such as 160 characters, before building it. That limit is a business choice for this example, not a WooCommerce default.
Register a small field before adding complex rules
WooCommerce’s official implementation tutorial documents registration on woocommerce_init and a minimum WooCommerce version of 8.9.0 for the base feature. Check your installed version against any newer options you plan to use.
Put store-specific behaviour in a small custom plugin so changing the theme does not remove it. The following is a minimal registration example for a staging store, not a complete gift-message feature:
add_action( 'woocommerce_init', function () {
if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
return;
}
woocommerce_register_additional_checkout_field( array(
'id' => 'kashii-store/gift-message',
'label' => __( 'Gift message', 'kashii-store' ),
'location' => 'order',
'type' => 'text',
'required' => false,
) );
} );
Keep the namespaced field ID stable once orders use it. It is the identifier your fulfilment integration will read, so changing it casually creates a data-mapping problem.
Validate the input and explain errors clearly
The registration API supports sanitization and validation callbacks. Use them to enforce the agreed rules on the server; a browser-only length check is not enough. The official tutorial above shows returning a WP_Error from a validation callback.
For the gift-message example, allow an empty value, normalize the submitted text, and reject a message that exceeds the agreed length. Tell the shopper how to fix it: “Please keep your gift message to 160 characters.” Test accented letters and Urdu as well as plain English, and choose a character-counting method that handles the text your customers actually enter.
Sanitization should not silently change the meaning of a personal message. Decide what line breaks and punctuation you support, then make the field label or help text clear. Escape the saved value when rendering it in a custom admin screen or document.
AI-generated photorealistic editorial close-up of hands placing a blank gift note into an envelope beside a boxed teal scarf. Illustrates order-specific gift-message fulfilment; not a real client order.
Generated editorial image: a gift note being packed with an order. This illustrates the workflow; it is not a screenshot or photograph of a client project.
Follow the value all the way to fulfilment
A successful checkout only proves that the order was accepted. It does not prove that your warehouse export, invoice plugin or courier connector received the extra field.
WooCommerce recommends its CheckoutFields helper methods for retrieving registered field values. Read order-specific information from the order object, rather than substituting a customer’s current profile values. That preserves what was provided for that purchase.
For this example, map the gift message to the packing workflow and check the exact output the team uses. If they print a custom pick list, verify it there. If they work from an external order system, confirm the integration sends the field. Avoid adding private messages to every email or export simply because the data is available.
Also decide who owns failures. If the order reaches the packing system without its message, staff need a visible exception to investigate. They should not have to guess whether a blank value means “no message requested” or “the integration dropped it.”
Test complete orders, not just field visibility
- Place a guest order with the field empty, then another with a valid message. Both should succeed.
- Submit an overlong value and confirm the error is understandable and the order is not accepted with invalid data.
- Buy again as a returning customer and confirm the previous gift message is not reused.
- Change the shipping address, refresh checkout, and retry a failed payment. Check that the intended value survives the relevant steps.
- Test mobile checkout and each enabled payment route, including express methods where offered.
- Inspect the saved order, customer-facing output and actual fulfilment export. Confirm the message is attached to the correct order.
If the field is missing, check the active checkout page, whether your plugin loads, and whether an order-location field has an Order information block available. If it appears but the value goes missing later, trace the saved order and export mapping before changing the frontend.
Keep checkout questions tied to a real job
An extra field should help someone complete the order. If nobody uses the answer, remove the question. If a delivery-date field is only a preference, label it that way; collecting a date does not reserve courier capacity.
For a related example of custom WooCommerce development, see my Swarm Rewards WooCommerce plugin project. It covers a checkout loyalty integration. The field pattern in this article is a separate implementation example, not a claim about that project’s Checkout Block compatibility.
If your store needs checkout fields connected to a fulfilment system or another API, I’m happy to discuss the workflow and the smallest useful implementation.
Documentation checked on 6 November 2026. Test against your store’s installed versions and extensions before deploying.
