A custom checkout field touches more than page design. Its value may be rendered in the browser, validated in PHP, saved to the order and sent to email or external systems. Failure at any step can stop order creation or produce an order missing required business data.
Preserve the failing value and error timestamp. Do not delete the field from production until you know whether fulfilment, tax or legal processes depend on it.
Determine where checkout stops
Submit once with controlled data and inspect the checkout request. Check whether WooCommerce creates an order before returning the error.
No order plus a validation message points towards field validation. An HTTP 500 points towards PHP. An order that exists without the field suggests saving or display logic, not order creation itself.
Check the gateway before repeating a live payment attempt.
Inspect the field definition
The rendered input needs a stable key, appropriate type, label and conditional required rule. Its browser name must match the key read by server-side code.
$value = isset( $_POST['delivery_note'] )
? sanitize_textarea_field( wp_unslash( $_POST['delivery_note'] ) )
: '';This example is suitable only for plain text. Dates, checkboxes, identifiers and structured data need validation appropriate to their meaning.
Never trust a hidden field simply because customers cannot see it; browser values can be changed.
Review validation callbacks
Find every hook that checks the field and note its priority. Validation must handle the field being absent, empty, an array or an unexpected type without causing a fatal error.
Conditional rules should use current posted values. For example, a delivery instruction may be required only for one shipping method. Comparing against an old method ID or translated label can reject every order.
Return a specific customer-safe message. Write technical details to a protected log without recording sensitive contents.
Check modern WooCommerce order storage
Stores using High-Performance Order Storage do not treat WordPress post metadata as the primary order model in the old way. Custom code should use WooCommerce order APIs and compatible hooks.
$order->update_meta_data( '_delivery_note', $value );
// Save in the lifecycle expected by the selected checkout hook.Do not call save() repeatedly inside loops or early checkout phases. Confirm the chosen hook provides a valid order object and runs once for the intended flow.
Test unusual but valid values
Reproduce with an empty optional value, accented characters, apostrophes, a maximum-length value and mobile autofill. A database column, remote API or overly strict regular expression may reject only certain inputs.
Set explicit length limits and show them to the customer. Avoid silently truncating values that fulfilment needs.
If the field uploads files or contains personal information, apply stricter access, type and retention controls.
Inspect integrations using the field
CRM, shipping, invoice and email code may assume the field always exists. A remote API timeout should not leave the customer staring at an endless spinner after payment.
Separate essential synchronous validation from work that can run safely after order creation. Queue non-critical exports and expose failures to administrators through logs or scheduled-action alerts.
Isolate without losing the business rule
Reproduce on staging with the same checkout type and storage mode. Disable only the custom field component or callback implicated by evidence. If checkout then works, continue narrowing to rendering, validation or saving.
A temporary production bypass requires business approval if the field is operationally required. Document how staff will collect the missing information.
Deploy and verify
Correct the field key, sanitisation, condition, hook or WooCommerce order API usage. Add a regression test for the exact failing value.
Complete guest and customer orders with relevant shipping and payment variations. Confirm exactly one payment, the field appears only to authorised staff where appropriate, emails remain correct and fulfilment receives it.
Recurring store care should test custom checkout data whenever WooCommerce, checkout blocks, payment or order storage changes. Custom fields are application code and deserve version control, review and monitoring.