Collect customer tax IDs

New customers

To enable tax ID collection for new customers, set tax_id_collection[enabled] to true when creating a Checkout Session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

Existing customers

Create a Checkout Session with an existing customer to add any tax ID information collected during checkout. The session saves the business name as the customer’s name, and adds the collected tax ID to customer.tax_ids.

When creating the Checkout Session, you must set customer_update.name to auto to prevent overriding the customer’s existing [name].

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

If you don’t have saved addresses for existing customers, you can use the billing or shipping address entered during checkout to assess their location. To use the billing address, set customer_update.address to auto. Setting this parameter to auto replaces the customer’s previously saved addresses with the address entered during checkout.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[address]"=auto \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

If you’re saving shipping addresses for existing customers, you can use the shipping address entered during checkout to assess their location. To use the shipping address, set customer_update.shipping to auto. Setting this parameter to auto replaces the customer’s previously saved shipping addresses with the address entered during checkout.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[shipping]"=auto \
  -d "shipping_address_collection[allowed_countries][0]"=DE \
  -d mode=payment \
  --data-urlencode return_url="https://example.com/return"

This example creates a session in payment mode with tax ID collection enabled. For subscriptions, make the same changes with the mode set to subscription.

Use Stripe’s Tax ID Element to collect tax IDs.

import {useMemo} from 'react',
import {loadStripe} from '@stripe/stripe-js';
import {CheckoutProvider, TaxIdElement} from '@stripe/react-stripe-js/checkout';

const stripePromise = loadStripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx', {
  betas: [
    'custom_checkout_tax_id_1',
  ],
});

const App = () => {
  const fetchClientSecret = useMemo(() => {
    return fetch('/create-checkout-session', {method: 'POST'})
      .then((res) => res.json())
      .then((data) => data.clientSecret)
  }, []);

  return (
    <CheckoutProvider
      stripe={stripePromise}
      options={{
        fetchClientSecret: () => fetchClientSecret,
      }}
    >
      <TaxIdElement />
    <CheckoutProvider>
  );
};

Checkout includes provided tax IDs on the resulting Session object. After each completed Session, Checkout emits a checkout.session.completed event that you can listen for in a webhook endpoint. If you want to retrieve the collected tax ID from the Session object, it’s available under the Session’s customer_details.tax_ids array:

{
  "object": {
    "id": "cs_test_a1dJwt0TCJTBsDkbK7RcoyJ91vJxe2Y",
    "object": "checkout.session",
    ...
    "customer": "cus_id_of_new_customer",
    "customer_details": {
      ...
      "tax_ids": [
        {
          "type": "eu_vat",
          "value": "FRAB123456789"
        }
      ]
    },
    ...
    "tax_id_collection": {
      "enabled": true
    },
    ...
  }
}

Checkout also saves collected tax IDs and business names to the Customer object if one is associated with the Session. A tax ID collected during checkout is accessible under the Customer’s customer.tax_ids array. You can also retrieve all tax IDs saved to a Customer with the Tax IDs resource by specifying the owner.type parameter to customer and owner.customer to the Customer’s ID. Every new tax ID includes an associated legal business name, which Checkout saves to the Customer’s name property. In doing so, the collected legal business name is always visible on any subscription invoices for that Customer.

In testing environments, you can enter any alphanumeric string that is in the correct format of a supported tax ID type (for example, DE123456789 for eu_vat). For a full list of example tax IDs you can reference our Customer Tax ID guide. You can also use our test tax IDs to test various verification state flows.