Collect customer tax IDs with Checkout

With tax ID collection enabled, Checkout shows and hides the tax ID collection form depending on your customer’s location. If your customer is in a location supported by tax ID collection, Checkout shows a checkbox allowing the customer to indicate that they’re purchasing as a business. When a customer checks the box, Checkout displays fields for them to enter the tax ID and legal entity name for the business. If available, Checkout uses the customer’s shipping address to determine their location, otherwise Checkout uses the customer’s billing address. Customers can only enter one tax ID.

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 "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success"

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.

You can additionally configure Checkout to create a new Customer for you using customer_creation. If you do, Checkout saves any tax ID information collected during a Session to that new Customer. If not, the tax ID information will still be available at customer_details.tax_ids.

Existing Customers

If you pass an existing Customer when creating a Session, Checkout updates the Customer with any tax ID information collected during the Session. Checkout saves the collected business name onto the Customer’s name property, and adds the collected tax ID to the Customer’s customer.tax_ids array. Since the collection of a business name could result in the Customer’s existing name being overridden, you must set customer_update.name to auto when creating the Session.

When collecting tax IDs for existing customers you can either base their location on existing addresses on the customer or the addresses entered during checkout. By default, Checkout looks for existing addresses on the customer to assess their location:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
"{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success"

If you don’t have the addresses of your existing customers saved, you can base their location on the billing or shipping address entered during Checkout. To specify that you want to use the billing address entered during Checkout to assess the customer’s location, you must set customer_update.address to auto. When setting customer_update.address to auto, Checkout replaces any previously saved addresses on the customer with the address entered during the session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
"{{CUSTOMER_ID}}" \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[address]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success"

If you’re collecting shipping addresses for existing customers, you must base their location on the shipping address entered during checkout. To do so, set customer_update.shipping to auto. When setting customer_update.shipping to auto, Checkout replaces any previously saved shipping addresses on the customer with the shipping address entered during the session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=cus_HQmikpKnGHkNwW \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -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 success_url="https://example.com/success"

The above code example creates a Session in payment mode with tax ID collection enabled. For subscriptions, make the same changes with the mode set to subscription.

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.