ECE: Add support for custom fields in block checkout #4390

annemirasol · 2025-06-03T17:32:53Z

Partially fixes STRIPE-205
Partially fixes #2969

Changes proposed in this Pull Request:

This PR adds support for ECE and custom checkout fields, limited to:

block checkout, and
fields added via Additional Checkout Fields API (i.e. woocommerce_register_additional_checkout_field()).

In subsequent PRs, we will add support for

custom fields added by third-party plugins that use extensions (block checkout only) (ECE: add support for extensions data #4394)
custom fields for classic checkout

Testing instructions

Add custom checkout fields to the block checkout:
- Install Code Snippets or a similar plugin, and add the snippet provided in the comment below.
As a shopper, add a product to cart and go to block checkout.
Notice the additional fields in the checkout form. Fill out these fields.
Use express checkout to complete your purchase.
Verify in the Order Confirmation page that the fields have been persisted.
- You may also check the wp_wc_orders_meta.
- The meta_key will be prefixed with _wc_billing/, _wc_shipping/ or _wc_other/.
Try using ECE in the product or cart pages.
- Verify there are no unexpected failures. See known limitations about required custom fields below.
- Verify it avoids using stale session data: since the custom fields are not presented to the shopper inside these pages, there should be no custom data stored for these orders.

Known limitations:

When marking a custom field as "required" in woocommerce_register_additional_checkout_field(), express checkout will fail when the data is not provided. This invariably means ECE is not usable outside of the block checkout page.
When validation fails, the error message from the server is displayed but the input field is not highlighted in red

Covered with tests (or have a good reason not to test in description ☝️)
Tested on mobile (or does not apply)

Changelog entry

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

Changelog Entry Comment

Comment

Post merge

Added testing instructions to the Release Testing Instructions wiki page (or does not apply)
Added the needs docs label (or does not apply)
Included this PR in the Release Thread scope (or does not apply)

annemirasol · 2025-06-03T20:21:58Z

Sample code snippet to add custom fields via the Additional Checkout Fields API:

	'woocommerce_init',
	function() {
		woocommerce_register_additional_checkout_field(
			array(
				'id'            => 'my-plugin/gov-id',
				'label'         => 'Government ID',
				'optionalLabel' => 'Government ID (optional)',
				'location'      => 'address',
				'attributes'    => array(
					'autocomplete'     => 'government-id',
					'aria-describedby' => 'some-element',
					'aria-label'       => 'custom aria label',
					'pattern'          => '[A-Z0-9]{5}', // A 5-character string of capital letters and numbers.
					'title'            => 'Title to show on hover',
					'data-custom'      => 'custom data',
				),
			),
		);
		
		woocommerce_register_additional_checkout_field(
			array(
				'id'       => 'my-plugin/marketing-opt-in',
				'label'    => 'Do you want to subscribe to our newsletter?',
				'location' => 'contact',
				'type'     => 'checkbox',
			)
		);
		
		woocommerce_register_additional_checkout_field(
			array(
				'id'          => 'my-plugin/how-did-you-hear-about-us',
				'label'       => 'How did you hear about us?',
				'placeholder' => 'Select a source',
				'location'    => 'order',
				'type'        => 'select',
				'options'     => [
					[
						'value' => 'google',
						'label' => 'Google'
					],
					[
						'value' => 'facebook',
						'label' => 'Facebook'
					],
					[
						'value' => 'friend',
						'label' => 'From a friend'
					],
					[
						'value' => 'other',
						'label' => 'Other'
					],
				]
			)
		);
	}

github-actions · 2025-06-05T19:38:08Z

📈 PHP Unit Code Coverage Report

Package	Line Rate	Health
includes/payment-methods/class-wc-stripe-express-checkout-element.php	51%	❌
Summary	44% (7168 / 16349)	❌

Copilot

Pull Request Overview

This PR adds support for passing custom checkout fields (registered via the Additional Checkout Fields API) through express payment methods in block checkout.

Exposes custom field configuration from PHP to JS for express checkout.
Enhances normalizeOrderData and related utilities to include custom billing, shipping, and additional fields.
Updates front-end error formatting and the API call to accept the full order payload.

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
readme.txt	Added changelog entry for block checkout custom fields support
includes/payment-methods/class-wc-stripe-express-checkout-element.php	Added `get_custom_checkout_fields()` to localize custom field IDs
client/express-checkout/utils/normalize.js	Extended normalizer to merge custom billing/shipping/additional fields
client/express-checkout/utils/index.js	Improved safety and early-return in error‐message parsing
client/express-checkout/utils/tests/normalize.test.js	Added tests covering additional fields and custom address fields
client/express-checkout/payment-flow.js	Added REST parameter error concatenation and formatting
client/blocks/express-checkout/hooks.js	Render multiline messages with `<br>` before setting error state
client/api/index.js	Renamed and streamlined `expressCheckoutECECreateOrder()` to send full order data
changelog.txt	Updated changelog entry

Comments suppressed due to low confidence (2)

includes/payment-methods/class-wc-stripe-express-checkout-element.php:235

The docblock says "field IDs" but the method returns an associative array of configs (key and location). Please update the @return description to reflect the actual structure.

* @return array Custom checkout field IDs.

client/express-checkout/utils/tests/normalize.test.js:137

There aren't tests for the non-block-checkout path of getAdditionalFieldsData or the custom-address helpers. Adding a test where isBlockCheckoutPage() is false would ensure stale data isn't sent.

describe( 'normalizeOrderData', () => {

client/express-checkout/utils/normalize.js

Co-authored-by: Copilot <[email protected]>

wjrosa · 2025-06-11T16:08:17Z

client/express-checkout/payment-flow.js

@@ -3,7 +3,12 @@ import { getErrorMessageFromNotice, normalizeOrderData } from './utils';

 const handlePaymentFlowException = ( event, exception, abortPayment ) => {
 	let errorMessage;
-	if ( exception.message ) {
+
+	if ( exception.code === 'rest_invalid_param' && exception.data?.params ) {


Optional: I would move this to a constant.

wjrosa · 2025-06-11T16:09:49Z

client/express-checkout/utils/normalize.js

-			postcode: shipping?.address?.postal_code ?? '',
-			method: [ event?.shippingRate?.id ?? null ],
-		},
+		billing_address: getBillingAddressData( event ),


Nice refactor!

wjrosa · 2025-06-11T16:12:06Z

client/express-checkout/utils/normalize.js

+
+	const data = {
+		first_name:
+			shipping?.name?.split( ' ' )?.slice( 0, 1 )?.join( ' ' ) ?? '',


Optional: Maybe we could have a helper method for the names, since both share the same logic

wjrosa · 2025-06-11T16:13:58Z

client/express-checkout/utils/normalize.js

+
+	const customerData = getCustomerDataFromStore();
+
+	if ( ! customerData || ! customerData.shippingAddress ) {


Suggested change

if ( ! customerData || ! customerData.shippingAddress ) {

if ( ! customerData?.shippingAddress ) {

wjrosa

Code is good and works as expected! Left some optional comments.

Verify in the Order Confirmation page that the fields have been persisted.

Try using ECE in the product or cart pages.

Verify there are no unexpected failures. See known limitations about required custom fields below.

Verify it avoids using stale session data: since the custom fields are not presented to the shopper inside these pages, there should be no custom data stored for these orders.

(custom field not displayed after checking out using the product page)

annemirasol force-pushed the add/ece-support-custom-fields branch 2 times, most recently from 583132b to c97c74f Compare June 3, 2025 18:40

Pass list of custom checkout fields to frontend

fe702fa

annemirasol force-pushed the add/ece-support-custom-fields branch from 2bbe0dd to 4dfbba7 Compare June 4, 2025 20:15

annemirasol added 3 commits June 4, 2025 15:16

Add additional fields data to POSTed order data

a28e277

Add custom billing and shipping address data to POSTed order data

f4a238a

Remove unnecessary call to getRequiredFieldDataFromCheckoutForm

c7a556c

annemirasol force-pushed the add/ece-support-custom-fields branch from 4dfbba7 to f82e492 Compare June 4, 2025 20:16

annemirasol self-assigned this Jun 4, 2025

annemirasol marked this pull request as ready for review June 4, 2025 20:28

annemirasol added 2 commits June 4, 2025 16:49

Display better error messages

cc723de

Add js tests

93ccf89

annemirasol force-pushed the add/ece-support-custom-fields branch from f82e492 to 93ccf89 Compare June 4, 2025 21:50

annemirasol added 3 commits June 4, 2025 16:54

Add changelog and readme entries

788650e

Avoid using stale data from session

cb0d8b9

Merge branch 'develop' into add/ece-support-custom-fields

6873d54

annemirasol requested review from a team and Copilot and removed request for a team June 5, 2025 20:35

Copilot AI reviewed Jun 6, 2025

View reviewed changes

client/express-checkout/utils/normalize.js Outdated Show resolved Hide resolved

client/express-checkout/utils/normalize.js Outdated Show resolved Hide resolved

client/express-checkout/utils/normalize.js Show resolved Hide resolved

annemirasol and others added 3 commits June 9, 2025 09:22

Fix logic for filtering custom fields

9eff4fa

Co-authored-by: Copilot <[email protected]>

Fix logic for filtering custom fields

d0b79c9

Co-authored-by: Copilot <[email protected]>

Merge branch 'develop' into add/ece-support-custom-fields

abf75bd

annemirasol requested review from a team and wjrosa and removed request for a team June 9, 2025 14:27

wjrosa reviewed Jun 11, 2025

View reviewed changes

wjrosa approved these changes Jun 11, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ECE: Add support for custom fields in block checkout #4390

ECE: Add support for custom fields in block checkout #4390

Uh oh!

annemirasol commented Jun 3, 2025 •

edited

Loading

Uh oh!

annemirasol commented Jun 3, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jun 5, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wjrosa Jun 11, 2025

Uh oh!

wjrosa Jun 11, 2025

Uh oh!

wjrosa Jun 11, 2025

Uh oh!

wjrosa Jun 11, 2025

Uh oh!

wjrosa left a comment

Uh oh!

Uh oh!


		const customerData = getCustomerDataFromStore();

		if ( ! customerData \|\| ! customerData.shippingAddress ) {

	if ( ! customerData \|\| ! customerData.shippingAddress ) {
	if ( ! customerData?.shippingAddress ) {

ECE: Add support for custom fields in block checkout #4390

Are you sure you want to change the base?

ECE: Add support for custom fields in block checkout #4390

Uh oh!

Conversation

annemirasol commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes proposed in this Pull Request:

Testing instructions

Changelog entry

Comment

Uh oh!

annemirasol commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 5, 2025

📈 PHP Unit Code Coverage Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wjrosa Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

wjrosa Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

wjrosa Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

wjrosa Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

wjrosa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

annemirasol commented Jun 3, 2025 •

edited

Loading

annemirasol commented Jun 3, 2025 •

edited

Loading