Tax identifier component

Gain a better understanding of the tax identifier component, how to create and mount it, as well as how to submit the information it collects

The tax identifier component can collect a customer's tax identification number.

To use the component, you'll need to create it, mount it, and submit its data.

The following are some of the following types of tax identifiers the component collects:

When the checkout-session's customerType is business and the customer's country is Germany, the component collects a Value Added Tax (VAT) number.

If your site sells outside the United States, particularly in the European Union, you'll likely need to implement the tax identifier component. This is especially true if you allow customers to make purchases on behalf of a business entity (i.e., B2B transactions).

If you know, before sending the create checkout-session request, whether customers are making the purchase as an individual or on behalf of a business, you can define customerType. Alternatively, by using the auto-collect customer type feature, you can configure the address component to get this information from customers

In some countries, customers must enter a tax identification number when making an e-commerce purchase. To access a list of these countries, refer to Supported tax identifiers.

In the data returned by onReady, you can use showTaxIdentifiers to determine whether the component must be displayed. Additionally, onChange allows you to determine when it's optional and required.

Once customers input a properly formatted value, Digital River creates a tax identifier and associates that object with the checkout-session. After the customer successfully makes payment and completes their purchase, Digital River adds that same taxIdentifiers[] to the order.

You should be aware, however, that a tax identifier won't affect how an order's taxes are calculated unless its state is pending or verified. For details, refer to How we validate tax identifiers.

Creating the tax identifier component

To create an instance of the tax identifier component, pass 'taxidentifier' to createComponent().

let taxIdentifierComponent;
taxIdentifierComponent = components.createComponent('taxidentifier');

Mounting the tax identifier component

To attach the tax identifier component to your DOM, pass the id of its container to mount().

<div id="tax-identifier-container" style="display: block"></div>

Submitting the tax identifier component

The tax identifier component exposes done(), which submits the customer's input and returns a boolean. It requires that you use the await operator and, therefore, must be called inside an async function.

const taxIdentifierComponentStatus = await taxIdentifierComponent.done();

If done() returns true, then this indicates that (1) customers entered a properly formatted value and Digital River used it to create a tax identifier and associate that object with the checkout-session or (2) customers entered an improperly formatted value (or nothing at all) but they're shopping in a country that gives them the option to supply a tax id number when making an e-commerce purchase but doesn't require it.

If true, your code can advance customers to the next stage in checkout.

A false value indicates that (1) the customer's country requires a tax id number to make the purchase and (2) customers either didn't provide a value or it's incorrectly formatted, and, as a result, Digital River cannot create a tax identifier.

If false, your application should contain logic that prevents customers from advancing to the next stage in the checkout.

In this case, the component prompts customers to re-enter a value and typically offers formatting assistance.

Example help text displayed when the customer's country is Germany, and they're checking out as a business entity.

Last updated