"Tax registrations" widget is missing its base field definition description

Done, ready to review!

Thank you very much @Grevil! This option caused a lot of confusion for us without a visible description. Sadly, the BaseFieldDefinition description isn't shown anywhere, just for internal use.

So this looks absolutely correct and now explains for what reasons countries need to be selected here! Small but effective change for UX!

♥️ Inline documentation right at the spot! 😉

This isn't the right fix... We need to add a setSetting('display_description', TRUE); to the field. See commerce_field_widget_single_element_form_alter().

Whoa thank you @jsacksick we were looking exactly for that, but seems to be documented nowhere! -.-

I'll add that to https://www.drupal.org/docs/drupal-apis/entity-api/defining-and-using-co... →

Much better, already thought about a core feature request, happy to hear that already exists!
Based on your feedback I found it here in code finally, but even Google isn't aware of it ... :D

Hero of the day once again @jsacksick

This isn't a core setting, but a Commerce core alteration... Not really sure why it was added though TBH...

Thanks! Adjusted accordingly!

Not sure we can append: "If items are shipped into the selected countries, their respective VAT rules are applied." Remember this screen isn't specific to VAT... There are also the Sales tax scenario etc.

Okay thanks once more! Then it seems to be something different in core with the same key?

Anyway... totally makes sense to me to reuse the description for the form, instead of duplicating it like in our first approach, so I really like that!

Not sure we can append: "If items are shipped into the selected countries, their respective VAT rules are applied." Remember this screen isn't specific to VAT... There are also the Sales tax scenario etc.

Well, we can of course remove or rephrase this. As you may have seen, we don't know about all those details, just trying to help other Drupal Commerce users by giving the best information possible. Of course, it should be correct.

Without that sentence I wouldn't have understood, at least, that this setting has the effect to use the selected countries VAT.
Don't want to take too much of your time, but could you perhaps rephrase it more correctly then?

A third party person should be able to understand the effects of this setting. Without the description (at all) I just thought this field is to define the tax residence of the company...

Without the description (at all) I just thought this field is to define the tax residence of the company...

This is what the field is used for... See the following response from ChatGTP which summarizes this:

When selling physical products to customers in different EU countries, the tax rate you should apply depends on whether you are registered for VAT in those countries and whether you meet the EU VAT distance selling thresholds or the OSS (One-Stop-Shop) scheme applies. Here’s a breakdown:

1. B2C Sales (Business to Consumer)
OSS Scheme (One-Stop-Shop):
If you are using the OSS scheme and your total cross-border EU sales exceed the EU-wide threshold of €10,000 per year (or the equivalent in local currency), you must charge the VAT rate of the customer's country.
Below the €10,000 Threshold:
If your cross-border sales remain below this threshold, you can charge your store's local VAT rate unless you voluntarily opt into the OSS scheme.
Distance Selling Rules (Without OSS):
Before the OSS scheme, you needed to register for VAT in each EU country where you exceeded their national threshold. With OSS, this is no longer required.
2. B2B Sales (Business to Business)
In a B2B transaction, the VAT is usually reverse-charged to the customer's country. This means you typically do not charge VAT but must include the customer's VAT number on the invoice.
Practical Scenarios:
Using OSS: Charge the customer’s VAT rate.
Not using OSS but under €10,000 sales threshold: Charge your store’s VAT rate.
Not using OSS and over the €10,000 sales threshold: Register in the customer's country or use OSS, and charge their VAT rate.
Compliance:
Ensure proper configuration in your e-commerce system to calculate and display the correct VAT rates based on the customer's shipping address.
Maintain records of where your customers are located and their VAT details for auditing purposes.

So it is up to the merchant to specify whether it is registered in other EU countries and if the 10k€ threshold is crossed.

Yeah I understand that from your explanations now, but I wouldn't have understood that before.
And of course we shouldn't get too specific in the description, but give the right general implications.

Maybe we can change: "If items are shipped into the selected countries, their respective VAT rules are applied" to If items are shipped into the selected countries, their respective tax rates are applied?

Yes, definitely! That's a clear improvement to me.

Should we also explain the other case?

If they the shipping country is not selected, ...

Well I'm not sure that the text added helps, because there is also the case of digital products, for which the customer zone is always used, regardless of the tax registration.

Yeah right... So should we leave it like this?

Other parts to the Commerce Tax Docs?

We should probably expand the Tax documentation yes... And maybe the description should include a link to that page.

Thanks, yes. I added the link. Good enough code-wise?

@anybody: Changed the text to:

The countries where the store is additionally registered to collect taxes. For further details see the Commerce Tax documentation.

Problem with the added sentence is that this only applies to the EU VAT plugin and could create confusion for other plugins...
The Commerce tax documentation needs to be expanded and the current rules should be described under the EU VAT section...

Are you ok with this?

Thank you very much, yes I understand!

Adding at least basic information to the docs would help a lot. I'm not sure how much we can help there, as we've seen multiple times now, that we don't fully understand the details yet. Please let me know otherwise.

Merged, thanks :).

Automatically closed - issue fixed for 2 weeks with no activity.