Additional Checkout Fields API.

[opr]

In WooCommerce Core, there is a filter which enables the fields displayed in the checkout form to be modified. Using this filter enables merchants and extension developers to add custom fields to their form to collect specific information that is not usually collected, e.g. VAT Number.

We plan to implement a solution which will allow merchants to create additional checkout fields in the Checkout block.

This GitHub discussion will serve as the main discussion point for this specific feature.

Update 1: Nadir shared below an RFC of what we will add and possible features.
Update 2: Call for testing: Additional Fields is now public under experimental prefix, please test it against your use case.
Update 3: API is now stable.

Requirements

• Extensions must be able to define custom fields to force-render in the Checkout block without requiring the merchant to add them.
• Extensions must be able to add a range of optional custom fields that the merchant may or may not add to the Checkout block.
• The custom fields added to the Checkout block must be discoverable by the Store API.
• The merchant/extension must be able to add fields of various types: e.g. Checkbox, Text field, email, number, select, multi select etc. (Please note, that some of these types may come later as a "part 2").

[webdados]

In a perfect world. this should be done with the previous PHP hooks, like "woocommerce_checkout_fields", "woocommerce_billing_fields" and "woocommerce_shipping_fields" and the core should take care of converting that into React.

[DavidAnderson684]

In one use case I have in an extension which I develop, a checkout field I add has these properties:

• Only appears if other conditions are fulfilled (in one example, only appears if the "Company name" field is non-empty).
• Whenever the value inputted changes, it is validated on the back-end (and the validation method needs to know the current state of the other fields on the checkout page)
• When various other checkout field values (billing or shipping country, shipping method, whether or not shipping to the billing country) are changed, re-validation also occurs since these changes may change the validation result

Another extension I develop has a custom field which has a time/date picker, though, the ultimate value for the field is the text (and the picker is a JavaScript library that updates that). This one also validates using the values of other fields from the checkout.

In a perfect world. this should be done with the previous PHP hooks, like "woocommerce_checkout_fields", "woocommerce_billing_fields" and "woocommerce_shipping_fields" and the core should take care of converting that into React.

I would have agreed with this before I began coding for the block-based checkout, but now having done so I'm not so sure. These PHP hooks require developers to code further JavaScript in order to fully implement the behaviour of their fields for fields that have custom validation or other behaviour like the above, and that JavaScript is tied to the implementation details of the shortcode-based checkout. Trying to make the same filters work on both checkouts could be a recipe for trouble. I think it'd be better to design a system that fits in the block-based world rather than trying to retro-fit an old system.

[opr]

Thanks for your input and for explaining your use cases! Super helpful to know what people want to achieve so we can guide them on the best solution. Explaining the use case will help us a lot more than just asking for certain hooks to be implemented, as we often have a more focused solution than a hook!

Only appears if other conditions are fulfilled (in one example, only appears if the "Company name" field is non-empty).

You can use the wc/store/cart data store to check if the company field is filled (More info on @wordpress/data)

import { useSelect } from '@wordpress/data';
const companyField = useSelect( ( select ) => select( 'wc/store/cart').getCartData().billingAddress.company );
...

Whenever the value inputted changes, it is validated on the back-end (and the validation method needs to know the current state of the other fields on the checkout page)

You can use extensionCartUpdate to send a request to the server side and get a new cart response. Your server-side code can add a validation message to the cart response.

• Adding data to cart endpoint
• Updating cart based on server-side code

(code examples in linked docs)

When various other checkout field values (billing or shipping country, shipping method, whether or not shipping to the billing country) are changed, re-validation also occurs since these changes may change the validation result

The useSelect above could be rewritten like so to get the whole address, then you could compare fields to decide if it needs revalidating.

import { useSelect } from '@wordpress/data';
const { billingAddress, shippingAddress } = useSelect( ( select ) => select( 'wc/store/cart').getCartData() );

You could copy our usePrevious hook too if you like, it's currently not exported, so you would need to copy it.

Another extension I develop has a custom field which has a time/date picker, though, the ultimate value for the field is the text (and the picker is a JavaScript library that updates that). This one also validates using the values of other fields from the checkout.

This can also be done using the information above! By the way there's a tutorial Tutorial: Extending the WooCommerce Checkout Block which does show an example of using the wc/store/validation store. I feel like this is the trickiest store to use as it's not super intuitive, we'll be working on improving the docs for this but until then if you need help with that just let us know!

[DavidAnderson684]

Thank you!
My main aim was to describe some real-world use cases we have to aid with planning the feature. But the above details are helpful in any case.
To be clear: since these things are already possible, do I understand rightly that what you're planning in this topic is how to make things more convenient, with less code?

Concerning:

You can use extensionCartUpdate to send a request to the server side and get a new cart response. Your server-side code can add a validation message to the cart response.

Will this mean that the validation message appears in the message section at the top of the checkout? Currently our validation message upon entering a value appears beneath the field itself. It'll be rather ugly if the page scrolls to the top to display validation messages whilst the user is still in process of typing the full entry (until the user has typed the full entry, it'll be invalid - but currently that's not a problem, because the page isn't scrolling anywhere to bring the validation messages into view).

[opr]

To be clear: since these things are already possible, do I understand rightly that what you're planning in this topic is how to make things more convenient, with less code?

Yes, to enable it to be done as part of the existing checkout forms, without needing to add a new block. And also enable this to be done via the block with no code, so a merchant can achieve it too (We hope to have it done programatically and via the UI).

Will this mean that the validation message appears in the message section at the top of the checkout? Currently our validation message upon entering a value appears beneath the field itself. It'll be rather ugly if the page scrolls to the top to display validation messages whilst the user is still in process of typing the full entry (until the user has typed the full entry, it'll be invalid - but currently that's not a problem, because the page isn't scrolling anywhere to bring the validation messages into view).

Just having the validation message in the cart response won't do anything by itself, you'll need to handle that too. You can use the validation data store to add your validation errors, and then you'll need to read from that data store to display the message below your field.

If there are errors present in that data store the checkout will not complete, so you'll need to ensure they're cleared when input is valid.

The area at the top of the checkout you're referring to is for "store notices" and is driven by the core/notices data store and unless the response from the server is an error response nothing will be automatically added to it on extensionCartUpdate

[DavidAnderson684]

Thanks again. Probably difficult to say, but do you have any sort of vague idea how long you think this project might take? I expect that I'm not the only developer asking himself "shall I code a forced inner block now, or shall I wait until they've implemented another (and easier) system first" ?

[opr]

but do you have any sort of vague idea how long you think this project might take

I totally understand your and the other developers' positions, but I don't have a timescale right now unfortunately. We're planning to start work on it in the next week or so, but it's quite unknown if we'll face any really tough blockers or if it will be smooth sailing all the way through. I don't want to mention any timescales while it's still uncertain. Thanks for your patience and understanding!

[dilrubaummer]

Is it possible to create a new block variation for the WooCommerce checkout block and replace inner blocks with custom blocks that have custom fields? Am I on the right track with this approach?

import {registerBlockVariation} from '@wordpress/blocks';
registerBlockVariation(
	'woocommerce/checkout',
	{
		name: 'checkout-form-block',
		title: 'Checkout Form Block',
        category: "checkout-block",
		attributes: {
			align: 'wide',
		},
        innerBlocks: [
           
			 [
				'core/paragraph',
				{
					placeholder: 'Enter content here...'
				} 
			],
            
        ],
        isDefault: true
	}
);

[opr]

Hi, I see an issue about including inner blocks that we "force" other blocks into, for example if you add the woocommerce/checkout-fields-block it automatically adds the contact information, shipping address, billing address, shipping method etc. etc. blocks, but if you include the blocks directly it seems like it works OK in my tests?

Out of interest what is the use case for this, why are you doing it? (Just curious!)

[dilrubaummer]

I am trying to create a custom checkout block that is similar to the WooCommerce checkout block. However, I need to make modifications to some of the existing inner blocks and potentially add new inner blocks as well.

[opr]

@dilrubaummer ok thanks for the info! Have you made any progress on this, is it working for you?

[senadir]

We will soon start working on adding custom fields to Checkout block. With this iteration, we hope to add a more complete solution, that interpolates well with Store API, and is backward-compatible to some extent.

The implementation would render fields in Checkout block, sync them between billing and shipping forms if needed, render them in the order screen and other screens, and accept them via Store API, and possibly more.

Pseudo-code API

Keep in mind that the following API is a rough idea and the final outcome might not be the same.

register_checkout_field(
	array(
		'namespace' => 'my_plugin',
		'id'        => 'gift_text',
		'label'     => __( 'Gift message', 'my_plugin' ),
		'type'      => 'text',
		'sections'  => [ 'additional_fields' ],
		'required'  => false
	)
);

add_action(
	'woocommerce_store_api_validate_my_plugin_gift_text_field',
	function( $value, $order ) {
		if ( is_invalid( $value ) ) {
			throw WP_Error( 'my_plugin_invalid_field', __( 'Gift field is invalid', 'my_plugin' ) );
		}
		return true;
	}
);

register_checkout_field(
	array(
		'namespace' => 'germanized_woo',
		'id' => 'vat_id',
		'label' => __('VAT ID', 'germanized_woo'),
		'type'      => 'text',
		'sections'  => [ 'billing_fields' ],
		'validation' => '[Dd][Ee][0-9]{9}',
		'country_limitation' => [ 'DE' ]
	)
);

Goal

The goal of this is to allow developers to register custom fields without fiddling around with React, or figuring out the whole lifecycle of a field.

Our second goal is to make those fields globally accessible, this means someone placing an order via Store API (like WooPay) can know which fields you need, collect them, and submit them.

The third goal is to set the stepping stone for adding custom fields directly to the editor. This means a merchant can add a field from the template editor, and have them work the same way as fields created pragmatically.

What we're not doing right now

For now, we will only target custom fields, core fields that are locale dependent will not be touched in this iteration. Such fields are still accessible to edit and manage via existing core filters.

Backward compatibility

Ideally, we don't want to break a lot of code, fields created via the woocommerce_checkout_fields should continue to work to a minimal degree, this is not something we can promise, and we would look into its possibility.

To use the new APIs as well as woocommerce_checkout_fields, you can register a field with the same ID, and the one registered using register_checkout_field would take precedence.

Under the hood

Beyond the pseudocode. The idea we have is that custom fields will be registered alongside core fields, all in the default addresses object and locale fields. This would allow us to provide first-degree support for rendering them in Checkout.

Existing fields settings

As with this, existing fields settings for the Company, Second Address, and Phone fields, will all move to the same place logically.

Fields visibility

By default, all registered fields will be visible in the order screen, the order confirmation screen, and confirmation emails.

Frontend handling

While not something we're highly supporting, custom fields would have the possibility to register custom frontend handlers, this would allow extra validation in the frontend.

We will also look into introducing the possibility to register custom render handlers, this would allow you to render your own component, it's, however, not recommended to do this, and would ideally, support this on our side in new types.

Conditional rendering

Depending on where you register your field, it will be conditionally rendered. Fields registered in both Billing and Shipping will show up in both, fields registered into one section while the other is set to be synced might show up in the visible form regardless. This is still under-research to see if it's something we want to do or not, and might start as an opt-in at the beginning.

Fields can also be rendered conditionally depending on the current country selected. This would align them with how locale field sets are rendered and shown.

For now, this will be the only conditional rendering we would offer.

Validation

For now, fields will continuously be pushed to the server when they're edited, and persisted to meta, this means you can run server validation on updates, not on order placement only.

We will consider adding an option for fields that don't need server validation and can be validated when the order is placed.

Storage

For now, all custom fields will be stored in metadata, we will not expand the core set of fields right now.

We might provide helpers in the Order object to fetch custom fields, but this is still unknown.

Initial types of fields supported

As a start, we will roll out a collection of field types that should cover the most common use cases:

• Text.
• Number.
• Select.
• Checkbox.

If there are any other fields you think we should support, let us know.

Open questions

We want to hear your feedback about this. If you're a plugin developer who bundles custom fields into Checkout, we would love to hear about them.

If your fields are dynamic in frontend, we would love to hear about how dynamic they're, and in what way they behave.

If you have any other questions or requests, do let us know.

[DavidAnderson684]

Sounds good, but one thing I notice:

"For now, this will be the only conditional rendering we would offer."

That wouldn't cover the real-world use case I mentioned above. Whether a VAT number field, for example, should be shown, can depend on all of these things:

• Company name (many shops have to collect a company name to compare it with a VAT number lookup to make sure they match, before dispatching the order - this can be required by a tax authority. Hence, they won't collect a VAT number without a company name).
• Shipping method - this can affect the deemed taxation country of the order (e.g. local pickup makes the taxation country of the transaction to be the pick-up location, whereas delivery makes the taxation country to be the buyer's location). The taxation country is an essential input for knowing whether a VAT number can be collected for the order to allow exemption or if it's unnecessary (because perhaps no exemption is possible based on the country).
• Shipping country or billing country (this can affect the deemed taxation country).
• A developer-added checkout field choice (in the EU, which country is deemed to be the taxation country can include input from the IP address, and if this conflicts with other countries, it can be necessary to ask the customer a further question to ascertain the deemed location - and once again, the deemed tax location then decides whether the customer ought to be allowed to enter a VAT number, or not allowed).

I have other extensions too in which the presence of a field depends upon the shipping method (e.g. whether to ask the customer to designate a time and date depends upon the chosen shipping method).

As you see, the conditions can get arbitrarily complex - and that to support very common needs (e.g. to do with VAT regulations).

I'd suggest that conditional rendering should allow developers to provide arbitrary JavaScript to decide upon the rendering conditions (which is what developers do on the current shortcode checkout - though this doesn't really hook into anything).

[DavidAnderson684]

I'm guessing that "Fields can also be rendered conditionally depending on the current country selected" is based upon the belief that "country" is a useful proxy for most things. But that's just not the case. As in the example above, EU (and other jurisdiction) tax laws have quite a few different inter-related inputs.

[webdados]

I guess we need to start somewhere, and adding a php approach to adding new fields is already a step forward.

[gabbygirl99]

Could this solve our problem of one entity paying for a (for example) class registration or ticketed event, and a second entity(ies) being the actual attendee, using those fields to specify names/options/choices and tickets? In the past, we've debated about adding more fields and how that might lengthen the registration process.

[senadir]

Hey @gabbygirl99 , yes, this could solve that, although I share your concern about the length of form.

[senadir]

@DavidAnderson684 I'd love to hear more use cases that doesn't explicitly involve a VAT field, as it seems the most complicated one.

For me, I don't see having a requirement on company field being filled as a requirement. As a reminder that you can still do server side validation and reject VAT values if no company value is present, given both fields are optional in your case.

For the Local Pickup case, I'd love if you can walk me through it more. I understand that taxation has to be passed on exchange location (In this case, the local pickup address). I understand here that visibility might be problematic but validation can still work fine server side to reject VAT codes that don't match the Local Pickup address country.

For such advanced use cases, you can still use CSS to hide fields if needed. We might expand the conditional rendering rules but for us it's essential that the list is static (so you get the same rules regardless of the current cart), make sense, and isn't too dependent on a specific implementation.

We're still very early on the code phase and each feedback we hear is essentially for us to test the limits here.

Also, keep in mind that each time you have to hide a custom field with CSS, we would love to hear about your use case, because whatever you did won't show up in a third-party Checkout like WooPay (the field would always be visible), and ideally we can expand conditional rendering rules in a meaningful way.

[DavidAnderson684]

Thanks for getting back!

For me, I don't see having a requirement on company field being filled as a requirement

All I can say is that a large number of the users of my VAT plugin disagree strongly with this (based on their feedback to us which led to implementing the feature, and pre-sales questions from potential users wanting to confirm that they will be able to do it). The requirements of VAT law across the world are very varied, to a degree that I had no idea of when I produced "v1.0" of the plugin!

"I'd love to hear more use cases that doesn't explicitly involve a VAT field, as it seems the most complicated one."

It was because the requirements were rich that I mentioned this case - presumably it's good to have a comprehensive view of what sort of requirements exist when planning what to implement, because a too-constricted design will be harder to fix later on, compared to having a more capable design at the beginning.

"As a reminder that you can still do server side validation and reject VAT values if no company value is present, given both fields are optional in your case."

Whilst some other users do want this too, this is a slightly different case and flow. This is "invalidate the number if no company name was supplied", which is different to "forbid number field display if no company name was supplied". From experience, some shops will find it annoying if they invite customers to enter a VAT number and then tell them it was invalid after they've done so - that's an inferior checkout experience to currently.

"but validation can still work fine server side to reject VAT codes that don't match the Local Pickup address country."

The situation may be that the store doesn't want to even ask the customer to supply a VAT number, or does, depending on the delivery method (because the delivery method can entirely the determine taxation country when its "local pickup"). Again, inviting a customer to add a VAT number, and then telling him that any non-empty VAT number is invalid, is a poor user experience. A lot of shops would prefer to stick to the shortcode checkout rather than have a UI that leads their customers into doing that.
One case where this is relevant is cross-border sales within the EU. It may be the case that VAT is always chargeable within the country (and hence always on local pickups - and remember this may include someone 1km down the road who happens to be cross-border - the within-EU border may be entirely invisible to all intents and purposes) and that the store does not wish to collect or process VAT numbers in that situation, but that if the package is instead being delivered and that crosses a (to all other purposes invisible) border, then VAT may be due if it's to an individual but exempt if it's to a business who can supply a number.

"For such advanced use cases"

When I first began selling a VAT plugin and suggesting to store owners that their country was "advanced", this tended to invite responses with links to their local tax documentation telling me this wasn't "advanced", it was simply the regulation for every store selling the kind of goods (or combinations of goods - physical, digital) where they lived, and as such, required in order to run a WooCommerce store for them. After hearing that more than once, I realised I just needed to implement the capability. And I'd be surprised if VAT numbers turn out to be the only thing that involves conditional checkout display rules with more than one variable in it in the world's collection of shops. Multi-variable display rules don't feel very exotic. Maybe you can implement just a generic callback so that developers can implement arbitrary logic in PHP, so that you don't have to worry about the possibilities of combinations?

"We might expand the conditional rendering rules but for us it's essential that the list is static (so you get the same rules regardless of the current cart),"

Well, in that case, I'd suggest you need to implement "and" and "or" conditions that can be nested. Such things aren't hard to parse, and they can be static and machine-readable, and those could make everyone happy still. e.g. A condition can be either "simple" (this field matches that value, or is non-empty, or is bigger than this, etc) or an "or" (which then has sub-conditions, one of which must match), or "and" (all sub-conditions must match). As I say, the rule list is then still static.

As you say, CSS is the fallback, but it'd be unfortunate to miss the opportunity to get it right first time; I'd argue that adding "or" and "and" sub-conditions in is only a small piece of work (the parser of the conditions just needs to recurse when it sees one).

[webdados]

For me, I don't see having a requirement on company field being filled as a requirement.

Exactly. In Portugal we all (persons and companies) have a VAT number and depending on what you're buying, filling in your personal VAT number (called "NIF": Número de Identificação Fiscal / Fiscal ID number) can give you benefits on your annual IRS).

[senadir]

Hello everyone!

A list of issues has been created for this project, feel free to follow the issue that interests you the most, let us know if an issue is missing.

If you have feedback about a specific issue, it's best to have it there (in that issue). If it's not covered, feel free to have it here.

https://github.com/woocommerce/woocommerce-blocks/issues/11584

[senadir]

As I'm working on fields locations, I'm trying to figure out if the following reasoning make sense.

This is an open question for the Woo team and third party developers.

Locations

We will allow fields to be inserted into 3 places:

• Contact step (alongside Email and marketing opt in).
• Address (Shipping and Billing)
• Additional Fields (alongside order note)

Storing

• Fields in the Address step will be stored to the customer account, for now, this will be locked in. Those are things like government IDs, VAT numbers, and any other address related info.
• Fields in Additional Fields section will only be persisted to the order, for now, this is locked in. Those will be things like Order note, Terms and Condition Opt, Delivery time, or packaging instructions.
• Fields in Contact step are still a gray area, we're likely to provide the option to make them be persisted to a customer account or not, they might be persisted by default unless otherwise.

Questions

What are the question fields you're interested in?
Where do you think your field fall in?
Most importantly: Do you have any fields that should only be in the Shipping Address, but not the Billing one, or vice versa?

[webdados]

@senadir Great work here! This is perfect.
My use case is the VAT number for an invoicing plugin, so although in the classic checkout I'm showing it alongside the "Billing" fields, in the new checkout it doesn't make sense as "Billing" is hidden by default. "Contact" is the perfect location.

[DavidAnderson684]

Where would the company name go in the above scheme? Shop owners tend to prefer the VAT number field to go next to the company name.

[senadir]

I also think that a VAT number is a natural part of an address, and it doesn't make sense to live with contact info.

When Shipping and Billing are synced, it make sense to render it there.

[opr]

When Shipping and Billing are synced, it make sense to render it there.

This seems like a sensible solution. It would have actually been a nice solve for the EU VAT Number plugin @ralucaStan mentioned here.

The field could be marked as "billing/shipping/both", affecting where it gets displayed in order emails and the admin dashboard.

[ralucaStan]

Fields in the Address step will be stored to the customer account, for now, this will be locked in. Those are things like government IDs, VAT numbers, and any other address related info.

@senadir I don't think that VAT Numbers or gov. ids are fields that are related to the (billing) address. They might be dependent on the data from the (billing) address, but they are not part of the information that identifies a shopper's address.

I am not a taxation expert but we might be confusing Billing information with Billing address.
I see the Billing information as something that contains: Billing address, Invoice information (VAT, Tax ID), Due date, etc. cc @pmcpinto @elizaan36

In the Checkout Block, the address display logic is different depending on cart content and user choices, and we risk having to deal with visibility issues for the VAT fields.

For example, the EU VAT Number extension adds a new checkout section that holds only VAT number. Structurally that would make more sense to me, especially since other fields might make sense contextually to be present there as well. Merchants can move that inner block wherever they want in the Checkout block.

Where would the company name go in the above scheme? Shop owners tend to prefer the VAT number field to go next to the company name.

For now, in the Checkout block, the Company is part of the address, but after reading this I wonder if this should be reevaluated.

---

Looking at all these comments I think it's time to reevaluate what we are trying to achieve with this project.

The intention was to allow merchants to collect additional fields useful to their order system. We've started this iteration with simple use cases in mind: special shopper notes, gift wraps, delivery preferences, CIF codes to generate the invoice.

But the discussion evolved to a really specific, pertinent and complex use case. I wonder if we shouldn't handle this one as a separate effort.

Because, the way I see it Additional Fields, the other possibility for Location we are offering, isn't fit for the Billing information fields. I wonder if Contact Info would be better? Thinking about the whole Checkout block UX, the context of the custom fields, and the context of VAT information we need to evaluate if it's better to simply create a new billing information section and create custom fields targeting it exclusively.

[ralucaStan]

Another discussion started by @passatgt kinda hints in the direction that billing information is separate from billing address

[webdados]

Let's try not to go out of focus here and get a first iteration of the functionality, or else we'll never going to have it: allow 3rd party developers to add custom checkout fields easily. Maybe allow them for now in 4 locations: contact, billing, shipping and additional fields. If possible in a retro-compatible way with the existing woocommerce_checkout_fields filter, but definitely without having to do React.

The idea of being able to create additional sections, like @ralucaStan mentioned about the EU VAT Number extension seems like an awesome functionality (and I REALLY want it), but I don't think it should be considered for a first iteration of this.

[senadir]

Creating additional steps might not be a developer API for now (but is something you can create yourself if you're comfortable with React) but might be something we allow merchants to do from the editor once we bring field editing fields to Gutenberg.

[senadir]

Should we allow different fields in Shipping and Billing?

Note: this is not a technical problem, but purely a UX one. I'd appreciate some product/design input into those proposals (@elizaan36 @pmcpinto), as well as examples of why a field would need to be in a single form and not both, and why that field can't live somewhere else.

Part of the additional fields project is deciding where we allow fields to be inserted.

We have a set of initial (soft) agreements that we're going with:

• Fields can be inserted into:
  • Contact Information.
  • Address Area (Shipping and Billing).
  • Additional Information.
• Fields will be saved to the order or customer state, depending on which place they're inserted:
  • Contact Information: Customer State, currently locked-in unless we have a good reason.
  • Address Area: Customer State, locked-in. (see reason why).
  • Additional Information: Order state, currently locked-in unless we have a good reason.

Allowing different fields while honoring the "Use same address for billing" raises a UX problem, how do you surface fields from a hidden form?

Up to now, every field that exists in the Shipping form also exists in the Billing form.
We had 2 exceptions to this in the history of Checkout:

• The Email field only exists in Billing and not Shipping, this led us to introduce the Contact step, under the hood, email is still part of billing, but UX wise, it's collected separately.
• The Phone field only exists in the Billing step, for us to fix that, we fixed it so that customers can have both Shipping and Billing phones, and for those values to be different if needed.

If we now start introducing a bunch of fields only in shipping or only in billing, we risk creating a confusing experience or a disjointed/incomplete one.

I propose a bunch of possible solutions to this:

Forgo the distinction between Shipping and Billing

For this solution, we don't introduce the possibility to have fields uniquely in shipping or billing, and only allow adding fields to both (Address).

New fields would behave the same way as other address fields, and can be synced between billing and shipping, and also surfaced and filled differently if the forms are not synced.

This would simplify the flow and create a predictable user experience.

Pros:

• Works the same way as other fields.
• Customers can have different values if needed.
• Doesn't cause a confusing experience.

Cons:

• Remove the flexibility of only adding the field to one form.
• Possibly encourages abusing other locations.

Remove the "Use same address for billing" when the forms differ

When we detect that the set of visible fields in Shipping is different from Billing, we show the billing form expanded as well.

Pros:

• This would always surface all different fields, making sure the customer is not confused.
• Customer would have to insert that value once (but still insert all other fields twice).

Cons:

• We risk making the form longer by having to fill both.
• This still doesn't solve the cases where Shipping and Billing are forced to sync (do we merge them), or when only billing is visible (digital product). I'd assume in that case, it should be expected that your field won't render.
  

Bring hidden fields to the other form.

In this solution, fields registered to a hidden form will be brought up to the other visible form, making sure they're always filled.

If a customer unsync the form, the field is removed from the shipping form for example and taking to the billing one.

Pros:

• Customer doesn't have to fill the form twice.
• The field is always surfaced.

Cons:

• It creates a confusing experience because the customer is filling that field on the premise of it being a shipping one, not a billing one.
• If the forms are not synced, the field would jump below, creating a jarring experience.


Add a new step (Additional Billing|Shipping information)

In this solution, we will keep Shipping and billing the behaving the same now. If a field is registered to a hidden form. We render a minimal form called Additional X information that only contains the extra fields.

Pros:

• The customer doesn't fill the form twice.
• The field is always visible.
• The customer doesn't fill a field assuming it's shipping while it's actually billing.

Cons:

• This would lengthen the form a bit further and add a step and make the experience a bit jarring.
• This still doesn't solve the case when a form is never rendered (Billing only order, Billing and Shipping being forced together) but is minor and can be communicated.

[pmcpinto]

@senadir thanks for outlining the main options. IMO Option 1(Forgo the distinction between Shipping and Billing) is the one that offers the best tradeoffs (simplifies the implementation and promotes a cohesive shopper experience), and we retain optionality (we can complement this with another solution in the future, in case we uncover valid use cases to allow different fields in shipping/billing).

Possibly encourages abusing other locations.

This seems like a reasonable risk, since it doesn't seem to be any worse than some of the UX tradeoffs we would have to make in the other proposed solutions.

cc @elizaan36

[elizaan36]

Thanks for putting together these solutions, @senadir.

I can see why Option 1, "Forgo the distinction between Shipping and Billing" is superior to the others when it comes to the form. It would be a major UX pitfall if a required field is located only in the billing address form, and this is missed if the "Billing same as shipping" checkbox is selected. Having both sections expanded is visually unappealing and overwhelming.

Now that I've explored solutions for the display of checkout data in different areas (Order confirmation, Email, and Order details) my main concern is that data isn't duplicated in these displays if it's not needed.

VAT is a good example – If this data is repeated between the shipping and billing summary it would be quite noisy. If the Shipping and Billing is synced at checkout, would it be possible to hide repetitive fields (such as phone number and custom fields) in the summary displays?

[passatgt]

Just to chime in, regarding the VAT number, in my extension i gone with this route:

So a checkbox or radio button in the first step(can be set in the inner block settings which one to use). If company selected, a required VAT number field shows up and i remove the checkmark from "Use same address for billing" to let the user know they need to fill in those details too(they can always click it back of course) with:

wp.data.dispatch('wc/store/checkout').__internalSetUseShippingAsBilling( (selectedCustomerType != 'company'))

Also i validate the VAT number on enter and in my case i can pre-fill the shipping/billing fields with the company's name and address using:

wp.data.dispatch('wc/store/cart').setShippingAddress( { 
    company: company,
     city: city,
     state: state,
     postcode: postcode,
     country: 'HU',
     address_1: address
});

wp.data.dispatch('wc/store/cart').setBillingAddress( { 
    company: company,
     city: city,
     state: state,
     postcode: postcode,
     country: 'HU',
     address_1: address
});

And i don't think you'd ever need a VAT number for shipping address.

[webdados]

And are you saving the VAT number on the customer data, in addition to the order?

[passatgt]

Yes, i store it in usermeta and order meta. If user meta exists, i prefill the field with the saved vat number(and check the company checkbox of course).

[webdados]

In my case, in Portugal, both people and companies have a VAT number, so I just don't need the checkbox.
Is your plugin free or premium? I could use some inspiration 🤣 while the developments being discussed here are not ready (which I guess will take a long time)

[mikejolley]

Forgo the distinction between Shipping and Billing

I think this would work well with the default fields, but when you start adding custom fields it could get worse. i.e. why would a single entity need to enter 2 VAT numbers for both addresses?

Add a new step (Additional Billing|Shipping information)

The merchant can control the new section title so this would work. Additionally or alternatively, the "contact information" section could be reused to labelled more generically so it could contain other fields.

Bring hidden fields to the other form.

@senadir Rather than bring hidden fields, could we not hide only the address fields?

So Billing and Shipping Address (or information?) blocks are always visible. We move the "use same address for x" checkbox to the Billing Address Block. If toggled on, no address fields show. If toggled off, the address fields show. Custom fields appear below everything else. This negates the need to move fields between sections as both sections can be visible at all times at the cost of a slightly longer form (extra heading).

[webdados]

The merchant can control the new section title so this would work. Additionally or alternatively, the "contact information" section could be reused to labelled more generically so it could contain other fields.

I like both options, but if allowing the creation of new sections is going to further delay the development, maybe phases should be considered. Phase 1: allow adding fields to existing sections (and if it's on the contact section or next to the order notes, the developer should be able to set if it's saved only to the order or also to the user profile for later usage as default value). Phase2: allow the creation of additional sections.

[senadir]

The VAT address would be synced between the 2 steps. Maybe we're again focusing too much on the VAT field which maybe should live elsewhere? For other address fields (pronouns, street type, country code for phone...) fields make sense to be on both.

[senadir]

I might start omitting VAT from examples for now 😅

[webdados]

@senadir Yes please :-D Let's focus on:

• Fields that are related to the address and should exist on both
• Fields that are not related to the address and should live somewhere else on the checkout form (contact section, new section or next to the order notes)

[senadir]

Also, going from forgo distinction options to other ones is easy, going back is not.

[ralucaStan]

One concern I have with Forgo the distinction between Shipping and Billing is that let's say tax id information is included for billing and that might surface on a shipping label. That information is private, has only billing/taxation purposes and ends up in places where it isn't relevant.

[senadir]

Things that surface in those places are things that the developer should be intentional about, They be will be visible in emails along other fields but otherwise each developer is responsible for where to show the field beyond.

[webdados]

Exactly. That's why WooCommerce have the address formats, which should be used in places like shipping labels, for example.
A new field will not show anywhere unless the developer specifically uses that field or changes the address format, for example.

Anyway, tax information should not live under the address sections anyway.

[DavidAnderson684]

I think that this presentation....

Contact step (alongside Email and marketing opt in).
Address (Shipping and then perhaps secondly Billing)
Additional Fields (alongside order note)

... has some fundamental problems that have no good way to resolve them, that are becoming evident through the above discussion. We can leave out the third, the "additional fields" - it's the other two that are the main problem.

These issues come from the fact that this (firstly contact, secondly shipping, thirdly and only potentially billing) does not map cleanly onto the three things which the checkout has to ascertain, and also from the fact that now the "billing" fields are being treated as secondary or dependent, when they have to be primary because they identify the legal purchaser.

So, here's what I mean by that. When a shop is making a sale, there are three fundamental things to be communicated to the store, for which there is a clean division between those things:

• Firstly, who is the legal entity (person, company) ordering this (and how to contact them by email) ?
• Secondly, how is this order to be paid for? (Or, put another way: who is being billed?)
• Thirdly, where should the order be sent? (Or, who is receiving the delivery?)

In the new block scheme, the customer is first asked how to contact (by email) the purchaser, and is then asked who is receiving the order, and then finally is asked who is being billed. In the resulting division in the user interface, part of the first question (who is the legal purchaser?) is asked first, then possibly the rest of the next question is being asked together with the third in the "shipping" section, but that section also includes a "use same details?" checkbox which, if not checked, instead means that some of the first issue is actually covered in the third section instead.

This is to say: notice that if the billing and shipping addresses are different, then this means that in the user experience, the legal entity doing the purchasing - which is in the user interface as the "billing first name", "billing last name" and "billing company" fields - comes late in the flow; and it's separated from the email address of that purchaser, which is asked for first. This then makes things quite confusing if more information needs to be requested about the purchaser's identity - for example, a business registration number, a government ID, a VAT number. This information is a "who is the legal purchaser?" question.... but it's not a "contact information" question (your government registration ID is not your contact information), and it's not a shipping question either. So, if your billing and shipping addresses are the same, then these questions don't belong clearly in either of the two displayed sections, so you'll end up having to create an entirely new section instead that comes after the others - an ugly experience in which the questions being asked go back and forwards between different areas (e.g. we'll ask you for the name of the purchaser in one section, and then for the purchaser's legal number in a different section). The experience is that the legal entity and their email address, is identified partly in section 1 (contact), partly in 3 (billing first/last names, company name) and partly in 4 (extra details) - that's ugly.

Compare this to the previous situation, which worked better. Previously, in the shortcode checkout, the billing first name, billing last name and billing company (and their legal country) are presented first. These fields are all effectively "who is the buyer?" questions. Thus, the identification of the purchaser came first, which was quite natural. The "billing address" section was effectively a combined "who is purchasing, and how are they paying?" section; and it was then natural for any further "who?" questions to be added as billing fields (e.g. goverment IDs for the company). But now, by making shipping primary, those two things have been divided, and the result is confusion over where different details should go - things that belong together are split. Consequently new sections will get invented instead, splitting them further.

So, I think putting shipping ahead of billing is simply a mistake, because it then splits the identification of the buyer over multiple parts, whereas before that was kept together. But if shipping must be put ahead of billing, then the fields previously (under the shortcode checkout) in "billing" that were also "who is the buyer?" fields should be moved up into 1., the "contact" section, and it should be relabelled to something like "Who is buying?" so that it is the logical place for all fields identifying the buyer (thus meaning no extra sections are needed).

[pmcpinto]

Thanks for your feedback. While showcasing the billing section upfront might suit certain businesses or scenarios, the general preference among most shoppers leans towards using a unified address for both shipping and billing. Therefore, defaulting to the same address simplifies the checkout process. It reduces the number of fields they need to fill out, making the overall experience faster and more user-friendly. For a deeper dive into this topic, the Baymard Institute provides useful insights in this article.

[DavidAnderson684]

I made a comment at the end of the previous post at another approach to how to overcome the messiness of spreading the buyer identification over two or three separation sections if it is decided that it is important to keep the shipping before the billing.

The complication of "is this a shipping field, is this a billing field?" is coming in for fields which are really primarily neither - they're customer identity identification fields.

Though, I do notice that the report you've linked acknowledges that its recommendations apply primarily to B2C sites, and that B2B sites and certain types of B2C sites will not want to implement its suggestions. So, if this research is being seen as something to give a strong weighting to, then the inference would be that WooCommerce should neither force one nor the other on all sites, but implement a setting?

[senadir]

I think considering this as a option to switch up in the future might make sense, given our limited spread now, it's unlikely to be done right now.

However, I do think WooCommerce should come with sane defaults that cater to the majority of its merchants.

[pmcpinto]

Yes. Adding an option to introduce more flexibility to how the shipping and billing addresses are displayed it's something that we'll consider. I'll add an issue about this to our backlog.

[bakkbone]

While showcasing the billing section upfront might suit certain businesses or scenarios, the general preference among most shoppers leans towards using a unified address for both shipping and billing. Therefore, defaulting to the same address simplifies the checkout process. It reduces the number of fields they need to fill out, making the overall experience faster and more user-friendly.

Not for gift-oriented industries. We maintain a floristry-specific plugin that extends Woo, and the approach to checkout in Blocks is wholly unusable for any of our clients. The sender and recipient must be collected, separately, every time - because orders going to the purchaser are incredibly rare for this type of business. So, they first and foremost need the purchaser's details - who do they contact if the recipient declines the gift, or if something is unavailable? Then the recipient (shipping address) along with some extra information we normally hook in to collect (gift message, delivery date, etc).

So bottom line, we need to be able to revert to the previous flow/order of fields because for our users, it is the only sane configuration.

[senadir]

Progress update

Thank you everyone for the feedback! I'd love to see more of it as it's shaping our next steps. This is a quick update of what we're thinking, from an engineering perspective and product prospective.

Conditional rendering

This was always on our mind but decided to increase its priority. Initially, we wanted to offer conditional rendering per country, we identified this was not a highly requested feature, but a complete conditional rendering (thanks for the feedback @DavidAnderson684), so things like selected shipping rate, values of existing fields, cart items, and anything related to the current session.

We are also looking if we can achieve a collect-once and hide kind of fields, like marketing opt-in, where you need to show it once, and once it's collected, you hide it. Opt-out can happen in other routes. Ideally we can achieve this using conditional rendering, if not, we would be looking at other routes. This is for now, can possibly be done using CSS and/or conditionally registering the field on PHP, but both are hacky.

Renaming meta fields

It was always part of our roadmap to have individual fields per meta field. One request (clearly communicated by @webdados) is that there needs to be a way to specify the meta field name. We're still not sure if we want to support this. After internal discussion between me, @opr, and @wavvves, we came to a middle ground to still support existing systems, without modifying the field name.

First, why we can't yet allow modifying the fields:

• We now have to ensure lack of conflict on 2 levels, the field ID and the meta key. This poses a higher conflict because we're dealing with historical data not just present one.
• We don't want to complicate the API further with extra parameters and supporting this on an internal level.
• Not having predictable, prefixed meta fields, risk us losing control of the UI we're building, as we're hoping to continue gracefully showing values even if a field is no longer there, or support showing them externally (think Woo App).

However, existing systems are high priority for us, and ensure easier codebases for you, as well as ease of migration from Shortcode Checkout to Block Checkout for merchants.

For this, we're considering adding a couple of adapters that would fit this use + other possible use cases.

A hook on saving a field

Whenever we're going to save a field, to customers or to an order, we're going to emit an action with that value, this would allow you to save the value into other places, like existing meta fields.

A hook on reading a field

Whenever we attempt to read a field and come back empty-handed (there's no value), we will trigger a filter, this would allow you to read the value from other places, like existing meta fields, or external systems if needed.

This would only happen once, future usage of that field on Checkout block will rely the copied value.

This should make it easy for you to migrate existing users from old Checkout to new one, as well as keeping your code simple without modifying the field name.

I believe this is an okay enough middle ground, it does mean saving the value twice, but gets us the best of 2 worlds.

[webdados]

Yeah! Glad to see this moving fast.

This was always on our mind but decided to increase its priority. Initially, we wanted to #42138, we identified this was not a highly requested feature, but a complete conditional rendering (thanks for the feedback @DavidAnderson684), so things like selected shipping rate, values of existing fields, cart items, and anything related to the current session.

Good one.

We are also looking if we can achieve a collect-once and hide kind of fields, like marketing opt-in, where you need to show it once, and once it's collected, you hide it. Opt-out can happen in other routes. Ideally we can achieve this using conditional rendering, if not, we would be looking at other routes. This is for now, can possibly be done using CSS and/or conditionally registering the field on PHP, but both are hacky.

I do not see this as a priority, but if it's easier to implement together with the conditional rendering, good.

We just need to make sure whatever is the way chosen to hide the fields (CSS or other), they're NOT processed into the order or the user, including not replacing or clearing any existing values on the user profile.

Regarding the meta field names, I agree it might important to keep the namespace on the UI, but the possibility to set the meta field name for order and user could be optional. The API would still be simple for those who do not specifically set the meta key names, and you could do your default naming.

Any getter/setter would just respect the values set via the API declaration of the new field. Default or custom.

I don't see how having the data in two places would simplify the process for anyone, including the WooCommerce core.

A hook on saving a field
Whenever we're going to save a field, to customers or to an order, we're going to emit an action with that value, this would allow you to save the value into other places, like existing meta fields.

So we would end up with the value in two places, right?

A hook on reading a field
Whenever we attempt to read a field and come back empty-handed (there's no value), we will trigger a filter, this would allow you to read the value from other places, like existing meta fields, or external systems if needed.

Assuming we were left with the value in both the default meta set by the core and the field set on the hook saving, how would it ever "come back empty-handed"? Wouldn't the value stored in the default field be returned? Honest question. Maybe I'm not getting this.

This is important, as plugins could have external interfaces or other ways to update the field on the user profile. Wouldn't this mean we would have to make sure any change to that field needs to be done in the two places?

This would only happen once, future usage of that field on Checkout block will rely the copied value.

I honestly didn't understood this. The checkout would get the value from the default field or the one set by the 3rd party developer? Again, the problem of external update of the field is very important here.

In short: allowing advanced API users to set their own meta keys for both order and user makes sure all the existing code will work, without having to worry about the "phantom" of the original field being there and never know when it comes back to haunt you 👻 🤣

[webdados]

Anyone got the validate_callback to work?

I'm testing this, theoretically forcing to always fail and it still does not work:

__experimental_woocommerce_blocks_register_checkout_field(
	array(
		'id'                => __NAMESPACE__ . '/testing_field',
		'type'              => 'text',
		'label'             => 'Testing field',
		'location'          => 'contact',
		'required'          => true,
		'attributes'        => array(
			'maxLength'        => 11,
		),
		'sanitize_callback' => __NAMESPACE__ . '\sanitize_testing_field', // Working and correctly calling the sanitize_testing_field function
		//'validate_callback' => __NAMESPACE__ . '\validate_nif', // Not working
		'validate_callback' => function( $field_value ) { // Not working
			return new WP_Error( 'testing_field', 'Not valid.' );
		},
	),
);

This is also not working:

// Validate via hooks - Simple validation with key and value
add_action(
	'__experimental_woocommerce_blocks_validate_additional_field',
	function ( WP_Error $errors, $field_key, $field_value ) {
		switch( $field_key ) {
			case __NAMESPACE__ . '/testing_field':
				$errors->add( 'testing_field', 'Invalid NIF.' );
				break;
		}
	},
	10,
	3
);

sanitize_callback is working just fine, btw.

Am I missing something really obvious here? I might 🤣

[senadir]

There is a bug in validation for fields in contact and additional, should be fixed with this PR #45840

[webdados]

🤣 Dude, this was driving me mad. I was like: "What the hell am I doing wrong on such a simple piece of code??"

[webdados]

Also the title attribute seems not to be working on select fields. Anyone can confirm?

[senadir]

FWIW @webdados it should only fail if the field is missing from the request, if the field is present and it's not validating, please let me know.

Also the title attribute seems not to be working on select fields. Anyone can confirm?

Yeah that's a limitation of the select component we're using, we're migrating to another one that should support it.

[webdados]

@senadir OK, no need to open and issue then, as you're already aware of this.

[aldavigdis]

What is missing in the __experimental_woocommerce_blocks_validate_additional_field function is a value parameter that would populate the HTML value attribute with a default value and pick which <option> is selected.

Otherwise, this is absolutely a step in the right direction and I'm already using if (function_exists statement in my code.

[senadir]

Would a default value be for a text input? can you provide use cases in which you need a static default value?

[aldavigdis]

@senadir I'll illustrate this with how I do this currently for the shortcode based checkout process, by hooking into woocommerce_before_checkout_billing_form, with slight modifications for clarity:

public static function render_classic_checkout_field(
    WC_Checkout $checkout
): void {
    $customer_id = $checkout->get_value( 'id' );
    if ( 0 !== $customer_id ) {
        $customer  = new WC_Customer( $customer_id );
        $government_id = $customer->get_meta( 'government_id', true );
    } else {
        $government_id = '';
    }

    woocommerce_form_field(
        'billing_government_id',

        // This is the `args` parameter.
        // It is only used for defining the block attributes, as the default value
        // is set in the next parameter.
        array(
            'type'              => 'text',
            'label'             => __( 'government_id', 'my-amazing-plugin' ),
            'id'                => 'checkout_government_id',
            'custom_attributes' => array(
                'pattern' => self::GOVERNMENT_ID_PATTERN,
            ),
        ),

        // This is where we use the `value` parameter to set a default value for our field
        self::format_government_id( $government_id )
    );
}

Here I retrieve the customer's government_id meta and set it as the default value for the government_id field that I then assign to the order during woocommerce_checkout_update_order_meta. This is important, because while the user's personal government ID can be assumed in most cases, if the customer is ordering for their business (or even a different division or subsidiary within it) then they'd use a different government ID.

I would expect __experimental_woocommerce_blocks_register_checkout_field() to work in the same way, without regressions.

As woocommerce_form_field already has a value parameter, then of course __experimental_woocommerce_blocks_register_checkout_field() should have the same parameter and I can't see this as being an edge case and without a value parameter, it is kind of useless to me.

__experimental_woocommerce_blocks_register_checkout_field() piggy-backs on CheckoutFields::register_checkout_field(), which does not accept a value key as it is to be set elsewhere.

[aldavigdis]

But to answer the question: Of course I need to set the default value of a text field. (And a drop-down menu for that matter).

[senadir]

While they're kinda similar, the new API is static, in a sense that it should not relay on customer session to display, this is essential because fields can be brought up beforehand and rendered or used to build a Checkout, way before a session is in place.

At a start, fields will always have previously saved values in them, if a user already inserted a value before, that value will show up in future orders.

We're also working on a way to bridge the gap, so that even if a user never inserted a value before, you can still populate it at load time, this is at time when a customer address is being passed to Checkout.

[senadir]

Backward compatibility

I recently pushed work to move additional fields from a global meta key to be a per meta key data, the new structure will save fields into 1 or 2 meta keys depending on their location:

• Address fields will be saved to both billing and shipping keys. Prefixed with _wc_billing or _wc_shipping.
• Contact and additional fields will be saved to a single field. Prefixed with _wc_additional.

I also added some docs here about reading the data.

We're aiming to release this with WooCommerce 8.9.0, in which the API is most likely to be graduated to stable.

When it comes to backward compatibility, I'm still looking into the best way to support that, but the good news is that there are some existing hooks you can use to preload data and react to saving data:

Reacting to saving a field

When a field is saved, WooCommerce will trigger "added_customer_meta" and "updated_customer_meta" (for customer fields) and "added_order_meta", assuming your field is named my-plugin-namespace/vat-id, you do the following code to save it into another field for your own goals:

add_action(
	'updated_customer_meta',
	function ( $id, $customer_id, $key, $value ) {
		if ( '_wc_billing/my-plugin-namespace/vat-id' === $key || '_wc_shipping/my-plugin-namespace/vat-id' === $key ) {
			// Do something with the value
		}
	},
	10,
	4
);

Same for orders:

add_action(
	'updated_order_meta',
	function ( $id, $order_id, $key, $value ) {
		if ( '_wc_billing/my-plugin-namespace/vat-id' === $key || '_wc_shipping/my-plugin-namespace/vat-id' === $key ) {
			// Do something with the value
		}
	},
	10,
	4
);

Providing an alternate value

When a field is being loaded from meta, WooCommerce will trigger a namespaced filter for that meta key, you can hook into it and return your value, each filter will only cover one area, billing, shipping, or additional:

add_filter(
	'woocommerce_customer_get__wc_shipping/my-plugin-namespace/vat-id',
	function ( $value, $customer ) {
		if ( '' === $value ) {
			// Read value from somewhere else
			$value = $customer->get_meta( '_vat_billing_id' );
		}
		return $value;
	},
	10,
	2
);

[webdados]

Backward compatibility

I recently pushed work to move additional fields from a global meta key to be a per meta key data, the new structure will save fields into 1 or 2 meta keys depending on their location:

• Address fields will be saved to both billing and shipping keys.
• Contact and additional fields will be saved to a single field.

Thanks for working on this @senadir

If I understand correctly, we'll be able to store Address fields in single meta (instead of the current serialized array) but Contact and Additional fields will remain to be stored only on the serialized array.

Did I get it correctly? If so, what's the reasoning behind the decision on treating them differently?

[senadir]

No, it means if you have a field in contact area called mynamespace/vat, it will be saved under the meta key of _wc_additional/mynamespace/vat. Sorry if it was not clear.

There will be no serialized array going forward.

[webdados]

There will be no serialized array going forward.

🙏

I recently pushed work to move additional fields from a global meta key to be a per meta key data

Where is this?

[senadir]

#46091

[senadir]

Renaming Additional fields

With the latest update, and exposing the concept of groups up to developers, I think we ended up creating some naming confusing, mainly around the work additional, to give an overview, we have:

• Additional Fields API: We're avoiding calling it custom fields to not mix up with existing custom fields functionality in WordPress, and because they're much more than just that.
• Additional location, alongside the Contact location and Address location, are where things are visually rendered in the Checkout, we might consider adding more locations in the future.
• Additional group, alongside Billing group and Shipping group, are where things are logically saved, they do not refer 1:1 to locations.

Possible naming suggestion:

• Additional Fields API would stay the same.
• Locations would be: Contact, Address, and Order.
• Groups would be: Billing, Shipping, Others.

[opr]

I'm fine with this naming strategy, however I would refer to the API as a whole "Additional Checkout Fields", it feels a little more descriptive of what it actually does. That said it's not a huge deal.

For the locations, I agree "Contact/Address/Order" make great sense.

As for groups, "Billing/Shipping/Other" makes sense (avoid using the plural, it should just be "other"). I didn't mention it in the review, but you'd need to update #46091 if we do change to "other" since we use additional currently.

[davide75]

In my plugin I'm adding Fiscal code and VAT code fields, and I would like to add a checkbox to toggle show/hide logic of these fields.
For example, I add a 'require an invoice' checkbox to the additional location:

array(
                'id' => 'namespace/blocks_billing_requireinvoice',
                'label' => __('Require an invoice', 'myplugin'),
                'location' => 'additional',
                'type' => 'checkbox',
                'required'=> false,
  
            ),

When checkbox is ticked In the additional section the customer would see Fiscal code and VAT code fields. It could be better if you may set 'required' as true only when fields are shown

[senadir]

Hey Davide! We have some similar requests to this. We're still looking for the best way to do it. A checkbox might not be the best way.

[davide75]

Ok I'm following 👍

[ludsloper]

Thank you for the hard work on this. Is there going to be support for the date type field as there was in the old api?
What is your suggested approach for inserting a custom (birth) date checkout field?

[senadir]

We do have plans to support date fields but it's not yet possible, you might need to build your own block for that. You can provide a "autocomplete" => "bday" in which browsers will autofill with the birthday, this is not the best workaround but that with custom sanitization/validation should get you close.

[ludsloper]

Very nice that there are plans to support date fields. Any rough estimate in which version or in what time span this will be?

[davide75]

Another scenario. I added this field:

array(
                'id' => 'namespace/blocks_billing_fiscalcode',
                'label' => __('Fiscal Code', 'namespace'),
                'location' => 'additional',
                'required'=> false,
 
            ),

I'd like to add a validation logic linked to the content of billing_country field.

I tried this:

add_action('__experimental_woocommerce_blocks_validate_location_additional_fields', 'mycustom_validate_checkout_blocks_fields', 10, 3);

function mycustom_validate_checkout_blocks_fields(\WP_Error $errors, $fields, $group) {
 var_dump('fields :', $fields);

}

but I only get values of fields added in additional location. How may I get the content of billing_country in that context?

[harasse]

Hello, I am probably late in expressing my needs. But here is mine. I am currently using in my applications, based on Woocommerce Core filters, an extension of WC addressing to pass from 2 lines to 4 lines.

For a transposition to WC checkout blocks, I will need to be able to choose the position of the 2 added fields and the placeholder ('priority' and 'placeholder' attr).

[opr]

Hi, thanks for your feedback.

You should be able to change the priority using the woocommerce_get_country_locale filter

For placeholder, we don't specifically allow setting that, however the label acts as a sort-of placeholder, so using that should be enough, that is in line with what the core address fields use in the Checkout block.

[senadir]

Visibility rules for fields

One common pattern that surfaced here was the need to have conditional rendering for fields, this is something that is currently possible statically, in 2 ways:

• You can hide optional additional fields based on the current country.
• You can hide any field based on country or some other static parameter (not session related).

Those are currently possible using core filters, we're looking to expand this so that you can:

• Hide required or optional additional fields.
• Do that based on current session, real time, and based on several conditions.

For this, we're going to work on a filtering engine, that works both on Checkout block (JS) and Store API (PHP), you get to provide a rule or several rules, that will decide whether this field should be collected or not, and if it should be validated on Store API or not.

Anatomy of a rule

When registering a field, you will be able to pass in an array of rules, that consist of the following:

[ source, operator, target ]

Sources and operators will be a provided, built-in list of options that you can pick from, and target is a value (string, number, boolean, or an array of them), for example, the following field will only be visible if the selected shipping method is my_cod_method:

[ 'cart.selected_shipping', 'is', 'my_code_method' ]

The following field will only render if the current cart contains a specific product with id 35

[ 'cart.items', 'contains', 35 ]

And the following would only render if cart contains a subscription product

[ 'cart.item_types', 'contains', 'subscription' ]

Possible operators

We're going to start with a limited set of operators that should behave like logical operators on databases and other systems:

• in and not_in would check if the source is contained in the target array, for example a selected_payment in an array of possible payment methods.
• contains and not_contains would check if the source array contains the target, for example available payment methods contains a COD method.
• is and not_is would be a type-loose compare, for example the selected shipping method is a specific one.
• less_than and greater_than would compare numeric values, as well as the length of arrays, so you can check if cart items are more than 5 or if the total is less than 100.

Possibles sources

We will start with a set of possible sources, sources have a hierarchy and the top categories include:

• cart.
• customer.
• order.
• address.

Those would allow built in values + arbitrary values that already exist on them, including other additional fields and extensions fields.

cart

Note that values in brackets are dynamic, and will be validated at run time.

• items: is an array of products IDs.
• item_types: is an array of product types.
• shipping: is an array of shipping methods IDs.
• selected_shipping: is an array of the selected shipping method ID. This might be soft handled as a string if there's a single package.
• needs_shipping: a boolean if the current cart will collect shipping or not.
• coupons: is an array of applied coupon codes.
• total: is the total amount of the cart, with decimal displacement, so $10 would be 1000.
  • subtotal: is the total amount of the cart before tax and shipping.
  • discount: is the total amount of the discount.
  • tax: is the total amount of the tax.
• extensions
  • [extension_namespace][extension_value]: depends on the registered value schema, but you can have your plugin register custom values here.

customer

• id: id of logged in customer, 0 if guest.
• email
• billing
  • company
  • city
  • state
  • postcode
  • country
  • phone
  • [additional_address_field]: Would be the value of an additional address field if it's set.
• shipping
  • company
  • city
  • state
  • postcode
  • country
  • phone
  • [additional_address_field]: Would be the value of an additional address field if it's set.

address

This is useful if you want visibility rule per shipping and billing, with same field, for example VAT and company + country.

• company
• city
• state
• postcode
• country
• phone
• [custom_address_field]: Would be the value of an additional address field if it's set.

order

• payments: is an array of visible, available payment methods IDs.
• selected_payment: Is the selected payment method, this is tricky and we might not support it because this is the last thing that's selected.
• fields:
  • note: Can be compared against as a string (to check the content) or as boolean (to check if the customer toggled the notes checkbox).
  • create_account: is a boolean, when an account is going to be created or not.
  • terms: is a boolean, when the terms are accepted or not.
  • [additional_field]: Would be the value of a contact or additional field if it's set.

Self comparison

We're unlikely to allow self comparison (a field including a visibility rule that targets itself), because the UX of that would be junky, but we're going to support that in a different way.

Future usage

Once we have this in place, we hope we can expand it further to also include core fields and maybe blocks.

Feedback

Feedback is welcome to see if we're missing any values or operators.

[webdados]

Wow. Really nice.

[FreekVR]

Thanks for the quick progress on this.

We have a plugin that separates the normal "address" fields into individual fields for a street and housenumber.

With the __experimental_woocommerce_blocks_register_checkout_field, unless I am missing something, I can only add a field to the very end of a specific location (like address). Would it, or is it, possible to add or change the order of fields, so that I can position my additional fields for example after the "last name" field?

[webdados]

Can you send the output of wcSettings.countryData.US.locale for your code?

I'm hooking to woocommerce_get_country_locale on plugins_loaded priority 2, so I don't think it's too late.

[webdados]

Never mind, other plugin was overriding this.

[webdados]

Working now. How to control it's full width or half width? For example if I move a field to the top of the form it will be side-by-side with First name and then Last name will be full width.

I would like to make mine full width so the names are side by side as default, but I'm afraid this might be hardcoded by position as I see no hints on the core fields declaration on CheckoutFields.php

[senadir]

It's something on our radar #42088 but we didn't get to you, you can do that with CSS for now.

Fields will be half if the next field after them is also half, but will be full otherwise.

[webdados]

Fields will be half if the next field after them is also half, but will be full otherwise.
How is it defined that the next is half? What makes them group together? Is it a CSS class or something like that? I've inspected the HTML and couldn't find how this is done. Again, it seems that's something hardcoded which needs some rethinking.

For reference, I fixed it this way, but feels a bit hacky:

<style type="text/css">
#shipping div[class*="mydomain/"]:first-child,
#billing div[class*="mydomain/"]:first-child {
	flex: 1 0 calc(100% - 8px) !important;
}
#shipping div[class*="mydomain/"]:first-child + .wc-block-components-address-form__first_name,
#billing div[class*="mydomain/"]:first-child + .wc-block-components-address-form__first_name {
	margin-top: 16px;
}
</style>

[senadir]

API marked Stable

Hey everyone! Additional fields API has been marked as stable (#46805), and will come out in WooCommerce 8.9 sometime mid May.

With that release comes some changes and features, some of them are not backward compatible, but overall, your code will continue to function just fine:

• additional location has been renamed to order to reflect its place and reduce ambiguity with the whole API name. Fields registered to additional will still continue to work fine but will log a warning.
• Logical group names have been update from billing|shipping|additional to billing|shipping|other.
• Fields are no longer saved under a single meta field, each field can have one or 2 fields for it. Address fields will have 2 fields, Contact and Order fields will have 1 field each.
• Note: Existing fields values will not load, if you had customers place values on the old API, those values will not show up after this update, the same for orders. You can read below as how to load them.
• You can now react to fields being read or saved, so that you can save a field to a different field name or do something else with it, or read a value from a different place, or provide a default value per customer.

For existing fields, assuming you had a field named namespace/my-field, registered to address, you can make that backward compatible by running this filter:

add_filter(
	'woocommerce_get_default_value_for_namespace/my-field',
	function ( $value, $group, $wc_object ) {
		if ( 'shipping' === $group ) {
			$key = '_additional_shipping_fields';
		} elseif ( 'billing' === $group ) {
			$key = '_additional_billing_fields';
		} else {
			$key = '_additional_fields';
		}

		$meta_data = $wc_object->get_meta( $key, true );

		if ( is_array( $meta_data ) && isset( $meta_data['namespace/my-field'] ) ) {
			return $meta_data['namespace/my-field'];
		}

		return $value;
	},
	10,
	3
);

So to summarize, from the experimental to stable, what's backward compatible is all the code, that will continue to function as is. But the data is not backward compatible, we didn't want to provide automatic data converting because of how risky it can be for a feature that was in experimental phase. Alternatively, instead of running the code above, you can write a task that moves from the old meta key to the new one.

We would love to hear your feedback and have you test the API, WC 8.9 beta will be released April 30th.

[webdados]

additional location has been renamed to order to reflect its place and reduce ambiguity with the whole API name. Fields registered to additional will still continue to work fine but will log a warning.

to "other", not "order", right?

[webdados]

Contact and Order fields will have 2 fields.

Shouldn't it be "1 field"

[senadir]

No, to separate and reduce confusion, the location names are separate from the logical storage groups.

Locations: Contact, Address, Order (and possibly more in the future).

Logic groups: Billing, Shipping (both belonging to Address), any thing else will be in Other.

As a developer, you will mostly care about Contact, Address, Order, it's only when you go deeper that you care about logical groups.

Previously, logical groups were named 'billing", "shipping", "" but we made it more explict.

[ludsloper]

Awesome! Are the extra features still considered for a future relrease? Like conditionally showing some checkouts fields (for example based on products in the cart)?

[senadir]

Yes, that's being actively worked on, you can follow this issue here.
#42138