Fix checkout validation for non-error update notices - #68360

Submission Review Guidelines:

• I have followed the WooCommerce Contributing Guidelines and the WordPress Coding Standards.
• I have checked to ensure there aren't other open Pull Requests for the same update/change.
• I have reviewed my code for security best practices.
• I have assessed the impact of this change and followed the applicable review requirements.
• Following the above guidelines will result in quick merges and clear and detailed feedback when appropriate.

Changes proposed in this Pull Request:

Classic checkout validated and highlighted untouched required fields whenever a checkout update returned any notice, including a success or info one. This fixes that without changing what the response already reports.

What changed

• result keeps its long-standing meaning: whether the response carries a rendered notice. A success notice still reads as failure there.
• A new has_errors boolean reports whether an error notice was rendered. Core reads it for notice clearing, field validation, and scrolling. Messages render whenever result reports a notice, as before, or the flag reports an error. A non-error notice clears only a stale place-order failure and leaves other notices alone.
• The handler falls back to result when has_errors is missing, is not a boolean, or reports an error without a notice to show, so a callback that answers this endpoint before Core does keeps behaving as it does today.

Why not just change result

The issue asks for exactly that, and an earlier revision of this PR did it. It breaks real consumers, so this PR deliberately diverges from the wording of the issue while fixing the behavior it reports.

One intentional behavior change

The shipping method radio focus keyed on 'success' === data.result, which stops meaning "no error" here. It now keys on the error flag, so focus fires for info and success notices where it did not before.

That widening exposed a latent crash, fixed here too. The focus restore dereferenced getElementById without a null check, so a checkout update that withdraws the selected shipping method threw before updated_checkout fired, cutting the event off from every listener. Reaching it on trunk needed a response with no notice at all; keying on the error flag would have extended it to every non-error response, including the notice a store shows while withdrawing a method.

Compatibility

The endpoint, hooks, fragments, reload, script handle, and emitted events are unchanged, and has_errors is additive. No database, migration, install-layout, or site-option effects. Multisite was not tested; the behavior is request- and session-scoped.

This changes a public response contract, so it needs independent human review.

Closes #40443.

Screenshots or screen recordings:

No screenshots are included. The observable change is behavioral: success notices remain visible without marking empty checkout fields invalid, while error notices retain the existing validation and scrolling behavior.

How to test the changes in this Pull Request:

Using the WooCommerce Testing Instructions Guide, include your detailed testing instructions:

1. From the repository root, run pnpm --filter=@woocommerce/plugin-woocommerce test:php:env -- --filter test_update_order_review_classifies_notices.

2. Confirm PHPUnit reports OK (7 tests, 69 assertions). The datasets cover a notice-free update, success, neutral, error, mixed success-plus-error, error-plus-reload, and an error kept off the page by a woocommerce_notice_types filter.

3. From the repository root, run pnpm --filter=@woocommerce/classic-assets test:js -- checkout-place-order-api.

4. Confirm Jest reports 20 passing tests. They cover notice rendering without field validation, preserved error behavior, scroll assertions in both directions, a response with no error flag, a response whose flag is not a boolean, a flag that reports an error with no notice to show, the shipping method focus restore with the input present and with it gone from the refreshed fragment, a stale place-order notice cleared by a later success notice, and a result: success response whose messages must not render.

5. Build the classic assets with pnpm wc:build:classic-assets.

6. Configure a classic shortcode checkout with a product in the cart, leave its required address fields empty, and add this temporary MU-plugin:

   <?php
   add_action(
   	'woocommerce_checkout_update_order_review',
   	function ( $posted_data ) {
   		parse_str( $posted_data, $data );
   		$mode = sanitize_text_field( wp_unslash( $data['billing_first_name'] ?? '' ) );
   
   		if ( 'trigger-success' === $mode ) {
   			wc_add_notice( 'Checkout details updated.', 'success' );
   		} elseif ( 'trigger-error' === $mode ) {
   			wc_add_notice( 'Enter the required checkout details.', 'error' );
   		}
   	}
   );

7. Enter trigger-success as the billing first name and run jQuery( document.body ).trigger( 'update_checkout' ); in the browser console.

8. Confirm the ?wc-ajax=update_order_review request returns HTTP 200 with has_errors: false and result: failure, that result value being the legacy signal this PR deliberately preserves. The success notice is visible, unrelated notices remain, and the other empty required fields are not marked invalid or scrolled to.

9. Enter trigger-error, trigger another checkout update, and confirm the request returns HTTP 200 with has_errors: true, the error notice replaces previous notices, empty required fields become invalid, and checkout scrolls to the error.

10. With that error notice on screen, place the order so it fails and leaves a woocommerce-NoticeGroup-checkout notice. Enter trigger-success, trigger another checkout update, and confirm the failed place-order notice is gone while any unrelated notice on the page is still there.

11. Add a second shipping method to the zone, select it so the update is triggered by the radio, and have the store withdraw that method on the next update. Confirm the console shows no error and that updated_checkout still fires.

12. Remove the temporary MU-plugin and disposable checkout fixtures.

Testing that has already taken place:

Automated

• PHPUnit --filter WC_AJAX: 70 tests, 291 assertions, 2 skipped, no failures, on PHP 8.1.34 and PHPUnit 9.6.35.
• Legacy Jest suite: 6 suites, 139 passed, 1 skipped.
• lint:php:changes and lint:changes:branch clean for PHP. ESLint reports 11 warnings and 0 errors, the same count the file already produces on trunk, so none are new.
• PHPStan on includes/class-wc-ajax.php: no errors.

Assertions were mutation-tested rather than trusted for passing

Ecosystem

Searched every published WordPress.org plugin for consumers of this response, which is how the three forks above were found and how their install counts were established.

Manual browser pass against a real classic checkout

Run on a local wp-env store after rebuilding the classic assets, on a shortcode checkout page with one product in the cart and every required field left empty. The served checkout.js was confirmed to contain the new flag and the page was hard-reloaded ignoring cache, so the executing script was the rebuilt one.

Scroll calls were counted by wrapping $.scroll_to_notices, and the payload was read from the updated_checkout event. The single invalid field seen in the third case is billing_last_name, from the existing focusout validation on the field used to park focus, not from the update handler, which would have flagged all five.

Not re-run for this revision

Earlier rounds included Infection mutation coverage and Semgrep. Both ran against the previous response shape that this revision replaces, so they do not cover the current code.

Milestone

• Automatically assign milestone for the next WooCommerce version

Note: Check the box above to have the milestone automatically assigned when merged.
Alternatively (e.g. for point releases), manually assign the appropriate milestone.

Changelog entry

• Automatically create a changelog entry from the details below.

• This Pull Request does not require a changelog entry. (Comment required below)

Use of AI Tools

Codex (OpenAI) was used for the original implementation, test development, adversarial acceptance review, runtime verification, and the first draft of this description.

Claude Code (Anthropic) was used for the review response that reworked the approach: verifying the reported compatibility break across the WordPress.org plugin corpus, designing the two-field response, writing and mutation-testing the tests, and rewriting this description.

🤖 Generated with Codex and Claude Code